home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 June / EnigmA AMIGA RUN 08 (1996)(G.R. Edizioni)(IT)[!][issue 1996-06][EARSAN CD VII].iso / earcd / comm1 / intsdkss.lha / socket.doc < prev    next >
Text File  |  1996-04-09  |  91KB  |  3,699 lines
  1. TABLE OF CONTENTS
  2.  
  3. socket.library/accept
  4. socket.library/Background
  5. socket.library/bind
  6. socket.library/ByteOrder
  7. socket.library/cleanup_sockets
  8. socket.library/ConfigureInet
  9. socket.library/connect
  10. socket.library/endgrent
  11. socket.library/endhostent
  12. socket.library/endnetent
  13. socket.library/endprotoent
  14. socket.library/endpwent
  15. socket.library/endservent
  16. socket.library/FD_SET
  17. socket.library/getdomainname
  18. socket.library/getgid
  19. socket.library/getgrent
  20. socket.library/getgrgid
  21. socket.library/getgrnam
  22. socket.library/getgroups
  23. socket.library/gethostbyaddr
  24. socket.library/gethostbyname
  25. socket.library/gethostent
  26. socket.library/gethostname
  27. socket.library/getlogin
  28. socket.library/getnetbyaddr
  29. socket.library/getnetbyname
  30. socket.library/getnetent
  31. socket.library/getpeername
  32. socket.library/getprotobyname
  33. socket.library/getprotobynumber
  34. socket.library/getprotoent
  35. socket.library/getpwent
  36. socket.library/getpwnam
  37. socket.library/getpwuid
  38. socket.library/getservbyname
  39. socket.library/getservbyport
  40. socket.library/getservent
  41. socket.library/getsockname
  42. socket.library/getsockopt
  43. socket.library/getuid
  44. socket.library/getumask
  45. socket.library/get_tz
  46. socket.library/inet_addr
  47. socket.library/inet_aton
  48. socket.library/inet_lnaof
  49. socket.library/inet_makeaddr
  50. socket.library/inet_netof
  51. socket.library/inet_network
  52. socket.library/inet_ntoa
  53. socket.library/listen
  54. socket.library/rcmd
  55. socket.library/reconfig
  56. socket.library/recv
  57. socket.library/select
  58. socket.library/selectwait
  59. socket.library/send
  60. socket.library/setgid
  61. socket.library/setgrent
  62. socket.library/sethostent
  63. socket.library/setnetent
  64. socket.library/setprotoent
  65. socket.library/setpwent
  66. socket.library/setservent
  67. socket.library/setsockopt
  68. socket.library/setuid
  69. socket.library/setup_sockets
  70. socket.library/shutdown
  71. socket.library/socket
  72. socket.library/strerror
  73. socket.library/syslog
  74. socket.library/s_close
  75. socket.library/s_crypt
  76. socket.library/s_dev_func
  77. socket.library/s_dev_list
  78. socket.library/s_dup
  79. socket.library/s_dup2
  80. socket.library/s_errno
  81. socket.library/s_getsignal
  82. socket.library/s_inherit
  83. socket.library/s_ioctl
  84. socket.library/s_release
  85. socket.library/s_syslog
  86. socket.library/umask
  87. socket.library/accept                                   socket.library/accept
  88.  
  89.    NAME
  90.     accept -- Accept new connection from socket.
  91.  
  92.    SYNOPSIS
  93.     ns = accept (s, name, len)
  94.     D0         D0 A0    A1
  95.  
  96.     int accept (int, struct sockaddr *, int *);
  97.  
  98.    FUNCTION
  99.     Servers using TCP (or another connection-oriented protocol) accept()
  100.     connections initiated by a client program.  The connections are
  101.     generally accept()ed on a socket which on which bind() and listen()
  102.     have been executed.  Unless there is an error, accept() will return
  103.     a new socket which is connected to the client.    The server can then
  104.     use the new socket ('ns') to communicate with the client (via send()
  105.     and recv()) and still accept() new connections on the old socket
  106.     ('s').
  107.  
  108.     'Len' should be initialized to the amount of space pointed
  109.     to by 'name.'  The actual size of 'name' will be returned in
  110.     'namelen' and 'name' will contain the name of the socket initiating
  111.     the connect().    This saves the server from needing to do a
  112.     getpeername() for new connections.
  113.  
  114.     accept() generally blocks until a client attempts a connect().
  115.     You may use select() to determine whether a connection is pending,
  116.     or use a non-blocking socket (see setsockopts()).
  117.  
  118.    INPUTS
  119.     s        - socket descriptor.
  120.     name        - name of the peer socket.
  121.     len        - pointer to the length of the sockaddr struct.
  122.               The value returned will be the actual size of the
  123.               sockaddr struct that was returned.
  124.  
  125.    RESULT
  126.     ns        - new socket descriptor or -1 (errno will be set to
  127.               reflect exact error condition).
  128.  
  129.    EXAMPLE
  130.  
  131.    NOTES
  132.  
  133.    BUGS
  134.  
  135.    SEE ALSO
  136.     socket(), bind(), listen()
  137.  
  138. socket.library/Background                           socket.library/Background
  139.  
  140.     What is a socket library?
  141.  
  142.  The standard programmer's interface to network protocols on most
  143.  Un*x machines is the Berkley socket abstraction.  It is usually
  144.  provided as a link library. You should have as documentation the
  145.  books "Unix Network Programming" by W. Richard Stephens
  146.  (Prentice-Hall, 1990) and "Internetworking with TCP/IP, Volume II"
  147.  by Douglas Comer and David Stephens (Prentice-Hall, 1991).  We
  148.  don't get a kick-back from Prentice-Hall, but we do use these books
  149.  every day and we do know that writing programs using TCP/IP and
  150.  sockets can be difficult.
  151.  
  152.     Why a shared socket library?
  153.  
  154.  A shared library provides many benefits.  First, it greatly reduces
  155.  code size.  Second, it is compiler-independent.  However, the most
  156.  important benefit is that it is easily upgradable.  New libraries
  157.  with bug fixes, speed improvements, or additional functions can be
  158.  utilized by existing code without recompilation.  In the case of
  159.  the socket library, this means we can later add support for name
  160.  resolution, better configuration, DES, etc.
  161.  
  162.     Who should use this?
  163.  
  164.  Everyone.  Our primary goal in writing this socket library is
  165.  compatibility.  BSD, SVR4, X/Open, POSIX and OSF sources have been
  166.  consulted when necessary.  All standard Unix socket functions, with
  167.  all their peculiarities have been faithfully ported :^)  Unfortunately,
  168.  due to the fact that these functions were not designed with shared
  169.  libraries or the Amiga in mind, some compromises were made.
  170.  
  171.     How to use this?
  172.  
  173.  See "What is a socket library?" above.  To port existing socket code
  174.  (from Un*x), you must:
  175.  
  176.     OpenLibrary the socket.library and call setup_sockets()
  177.     not call read() or write() on sockets (use send() and recv())
  178.     call s_close() rather than close() for sockets
  179.     call s_ioctl() rather than ioctl() for sockets
  180.  
  181.  On Un*x machines, the calls read(), write(), close(), ioctl(), etc.
  182.  functions are just calls to the kernel which can deal with sockets
  183.  and other files.  Obviously, this is not possible with a shared
  184.  library on a machine where these functions come from link
  185.  libraries, hence the s_*() functions.
  186.  
  187.     About errno:
  188.  
  189.  'C' programmers should be familiar with the global variable
  190.  'errno.'  It is used extensively in standard socket implementations
  191.  to provide details about error conditions.  We take care of this in
  192.  the shared library by passing a pointer to 'errno' into the shared
  193.  library with setup_sockets().  You can, of course, pass a pointer
  194.  to any longword-aligned, four-byte chunk of memory you own, so this
  195.  will work for non-'C'-language programmers.
  196.  
  197.     About integers:
  198.  
  199.  All integers are assumed to be 32-bit.  None are specified as long
  200.  in order to maintain Un*x compatibility.  If you are using a
  201.  compiler which doesn't use 32-bit ints, you must make sure that all
  202.  ints are converted to longs by your code.
  203.  
  204.     About assembly langauge:
  205.  
  206.  To be complete, we probably should include assembly header files.
  207.  We don't.
  208.  
  209.     About the get*() functions:
  210.  
  211.  This is standard with the Un*x functions, too, but is worth noting:
  212.  These function return a pointer to a static buffer.  The buffer returned
  213.  by a call to getX*() is cleared on the next invocation of getX*().  For
  214.  example, the buffer pointed to by the return of gethostent() is cleared
  215.  by a call to gethostent(), gethostbyaddr() or gethostbyname(), but not
  216.  by a call to getprotoent(), etc.
  217.  
  218.  As noted in the autodocs, none of the get*ent(), set*ent() or end*ent()
  219.  functions should normally be used except in porting existing programs
  220.  (and internally).
  221.  
  222.     About library bases:
  223.  
  224.  The shared socket library returns a different library base for each
  225.  OpenLib() and uses these different library bases to keep track of some
  226.  global data for each opener.  If you start a new process with a new
  227.  context, the new process must open and initialize socket.library.  Mere
  228.  tasks should not access the socket.library, only processes should.
  229.  
  230.     Example:
  231.  
  232.  /* your includes */
  233.  #include <exec/types.h>
  234.  #include <exec/libraries.h>
  235.  #include <exec/execbase.h>
  236.  #include <dos/dos.h>
  237.  #include <proto/all.h>
  238.  #include <sys/types.h>
  239.  #include <sys/socket.h>
  240.  #include <stdio.h>
  241.  #include <errno.h>
  242.  
  243.  /* the next two lines must always be here */
  244.  #include <proto/socket.h>
  245.  
  246.  /* this is the maximum number of sockets that you want */
  247.  #define MAXSOCKS 10
  248.  
  249.  main()
  250.  {
  251.     if((SockBase = OpenLibrary( "inet:libs/socket.library", 6L )) == NULL) {
  252.         printf("Error opening socket.library\n");
  253.         exit(10);
  254.     }
  255.     setup_sockets( MAXSOCKS, &errno );
  256.  
  257.     /* normal socket code... (see AS225 dev disk for complete examples) */
  258.  
  259.     cleanup_sockets();
  260.     CloseLibrary( SockBase ) ;
  261.  }
  262.  
  263.     Legalese:
  264.  
  265.  This shared socket library (and it's documentation) are Copyright © 1995
  266.  Interworks.  All Rights Reserved.  The shared socket library was based on
  267.  code from Commodore, Inc., written by Martin Hunt.  This version was
  268.  written by Jim Cooper and Michael B. Smith of Interworks.  Documentation
  269.  by Jim Cooper, Michael B. Smith, and others.
  270.  
  271.  Parts of this shared socket library and the associated header files are
  272.  derived from code which is:
  273.  
  274.  Copyright (c) 1980-1995 Regents of the University of California.
  275.  All rights reserved.
  276.  
  277.  Redistribution and use in source and binary forms are permitted
  278.  provided that the above copyright notice and this paragraph are
  279.  duplicated in all such forms and that any documentation,
  280.  advertising materials, and other materials related to such
  281.  distribution and use acknowledge that the software was developed
  282.  by the University of California, Berkeley.  The name of the
  283.  University may not be used to endorse or promote products derived
  284.  from this software without specific prior written permission.
  285.  THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
  286.  IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  287.  WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  288. socket.library/bind                                       socket.library/bind
  289.  
  290.    NAME
  291.     bind -- Bind a name to a socket.
  292.  
  293.    SYNOPSIS
  294.     return = bind (s, name, namelen)
  295.     D0           D0 A1    D1
  296.  
  297.     int bind (int, struct sockaddr *, int);
  298.  
  299.    FUNCTION
  300.     Assigns a name to an unnamed socket.
  301.  
  302.     Connection-oriented servers generally bind() a socket to a well-
  303.     known address and listen() at that socket, accept()ing connections
  304.     from clients who know the address.
  305.  
  306.     Connectionless servers generally bind() a socket to a well-known
  307.     address and recvfrom() that socket.
  308.  
  309.     Most servers should build 'name' from a well-known port obtained
  310.     from getservbyname().  Hard-coded ports are often used in prototype
  311.     servers, but should never be used in production code.  For more
  312.     information on port numbering, see your favorite TCP/IP refrence.
  313.  
  314.    INPUTS
  315.     s        - socket descriptor.
  316.     name        - address to bind to socket 's.'
  317.     namelen     - length (in bytes) of 'name.'
  318.  
  319.    RESULT
  320.     return        - 0 if successful else -1 (errno will contain the
  321.               specific error).
  322.  
  323.    EXAMPLE
  324.  
  325.    NOTES
  326.  
  327.    BUGS
  328.  
  329.    SEE ALSO
  330.     socket(), listen(), accept()
  331.  
  332. socket.library/ByteOrder                             socket.library/ByteOrder
  333.  
  334.    NAME
  335.     byteorder -- Macros to convert between host and network byte order.
  336.  
  337.    SYNOPSIS
  338.     #include <sys/types.h>
  339.     #include <netinet/in.h>
  340.  
  341.     netlong   = htonl ( hostlong );
  342.     netshort  = htons ( hostshort);
  343.     hostlong  = ntohl ( netlong );
  344.     hostshort = ntohs ( netshort);
  345.  
  346.    FUNCTION
  347.     These routines convert between host byte order to network byte
  348.     order.  This is necessary because not all CPUs store words and
  349.     longs in the same manner.  Some CPUs, called "Big Endian," store
  350.     words as high byte followed by low byte.  Others, called "Little
  351.     Endian," store a word as low byte followed by high byte.
  352.  
  353.     Big endian machines include IBM mainframes and Motorola 68000
  354.     family machines.  Little endian machines include DEC VAXen and
  355.     Intel 80x86 family CPUs.
  356.  
  357.     Network order is big endian.  Therefore, on big endian machines,
  358.     these functions are null macros.
  359.  
  360.    EXAMPLE
  361.  
  362.    NOTES
  363.     These macros are provided for portability.
  364.     They are null macros on the Amiga.
  365.  
  366.     #define htons(x)    (x)
  367.     #define ntohs(x)    (x)
  368.     #define htonl(x)    (x)
  369.     #define ntohl(x)    (x)
  370.  
  371.    SEE ALSO
  372.  
  373. socket.library/cleanup_sockets                 socket.library/cleanup_sockets
  374.  
  375.    NAME
  376.     cleanup_sockets -- Free global data for sockets.
  377.  
  378.    SYNOPSIS
  379.     cleanup_sockets ();
  380.  
  381.     void cleanup_sockets (void);
  382.  
  383.    FUNCTION
  384.     This function frees all signals and allocated memory.
  385.     It closes all open sockets.  This function should be
  386.     called after all socket functions are completed and before
  387.     CloseLibrary().
  388.  
  389.    INPUTS
  390.     None.
  391.  
  392.    RESULT
  393.     None.
  394.  
  395.    NOTES
  396.     Since 'socks' is now allocated in the library initialization code,
  397.     we do the deallocation in the library cleanup.    Also, since we aren't
  398.     allocating based on the 'maxsocks' parameter to setup_sockets(), we
  399.     scan the entire array - we don't just stop at the 'maxsocks - 1' entry,
  400.     in case they overran their original request.  This takes care of the
  401.     program requesting 0 sockets, but opening one anyway...
  402.  
  403.    BUGS
  404.  
  405.    SEE ALSO
  406.     setup_sockets()
  407.  
  408. socket.library/ConfigureInet                     socket.library/ConfigureInet
  409.  
  410.    NAME
  411.      ConfigureInetA -- Set or change socket.library configuration states
  412.  
  413.    SYNOPSIS
  414.      ConfigureInetA (taglist)
  415.               A0
  416.  
  417.      void ConfigureInetA (struct TagItem *);
  418.  
  419.    FUNCTION
  420.      Allows the caller to manipulate certain socket.library operating
  421.      parameters, such as whether I-Net 225 operates as a gateway or not.
  422.  
  423.    INPUTS
  424.      taglist - A taglist containing tags defined in <netinet/inetconfig.h>
  425.  
  426.    RESULT
  427.      None.
  428.  
  429.    EXAMPLE
  430.  
  431.    NOTES
  432.  
  433.     I-Net 225 ONLY.
  434.  
  435.    BUGS
  436.  
  437.    SEE ALSO
  438.  
  439. socket.library/connect                                 socket.library/connect
  440.  
  441.    NAME
  442.     connect -- Connect to socket.
  443.  
  444.    SYNOPSIS
  445.     return = connect (s, name, namelen)
  446.     D0          D0  A1     D1
  447.  
  448.     int connect (int, struct sockaddr *, int);
  449.  
  450.    FUNCTION
  451.     To communicate with a server using a connection-oriented protocol
  452.     (i.e. TCP), the client must connect() a socket obtained by the
  453.     client (from socket()) to the server's well-known address.  (The
  454.     server will receive (from accept()) a new socket which is connected
  455.     to the socket which the client is connect()ing to the server.)
  456.  
  457.     Clients of a connectionless server (i.e. one using UDP) can use
  458.     connect() and send() rather than always using sendto().  In this
  459.     case, no actual connection is created, the address to send to is
  460.     just stored with the socket.
  461.  
  462.     Most clients should build 'name' from a well-known port obtained from
  463.     getservbyname().  Hard-coded ports are often used in prototype
  464.     clients, but should never be used in production code.  For more
  465.     information on port numbering, see your favorite TCP/IP refrence.
  466.  
  467.    INPUTS
  468.     s        - socket descriptor.
  469.     name        - address of socket to connect 's' to.
  470.     namelen     - length of 'name.'
  471.  
  472.    RESULT
  473.     return        - 0 if successful else -1 (errno will contain the
  474.               specific error).
  475.  
  476.    EXAMPLE
  477.  
  478.    NOTES
  479.  
  480.    BUGS
  481.  
  482.    SEE ALSO
  483.     socket(), bind(), listen(), accept()
  484.  
  485. socket.library/endgrent                               socket.library/endgrent
  486.  
  487.    NAME
  488.     endgrent - Closes the group file.
  489.  
  490.    SYNOPSIS
  491.     endgrent ()
  492.  
  493.     void endgrent (void);
  494.  
  495.    FUNCTION
  496.     Closes the group file if it was open. Resets the 'flag' that
  497.     may have been set by setgrent().
  498.  
  499.    INPUTS
  500.     None.
  501.  
  502.    RESULT
  503.     None.
  504.  
  505.    NOTES
  506.  
  507.     I-Net 225 ONLY.
  508.  
  509.    SEE ALSO
  510.     getgrent(), setgrent()
  511.  
  512. socket.library/endhostent                           socket.library/endhostent
  513.  
  514.    NAME
  515.     endhostent -- Closes the hosts file ("INet:db/hosts").
  516.  
  517.    SYNOPSIS
  518.     endhostent ()
  519.  
  520.     void endhostent (void);
  521.  
  522.    FUNCTION
  523.     Closes the host file if it is open.  Only needed if sethostent()
  524.     or gethostent() have been called.
  525.  
  526.    INPUTS
  527.     None.
  528.  
  529.    RESULT
  530.     None.
  531.  
  532.    EXAMPLE
  533.  
  534.    NOTES
  535.  
  536.    BUGS
  537.  
  538.    SEE ALSO
  539.     gethostent(), gethostbyname(), gethostbyaddr(), sethostent()
  540.  
  541. socket.library/endnetent                             socket.library/endnetent
  542.  
  543.    NAME
  544.     endnetent -- Closes the networks file.
  545.  
  546.    SYNOPSIS
  547.     endnetent ()
  548.  
  549.     void endnetent (void);
  550.  
  551.    FUNCTION
  552.     Closes the host file if it is open.  This is only needed if
  553.     setnetent() or getnetent() has been called.
  554.  
  555.    INPUTS
  556.     None.
  557.  
  558.    RESULT
  559.     None.
  560.  
  561.    EXAMPLE
  562.  
  563.    NOTES
  564.  
  565.    BUGS
  566.  
  567.    SEE ALSO
  568.     getnetent(), getnetbyname(), getnetbyaddr(), setnetent()
  569.  
  570. socket.library/endprotoent                         socket.library/endprotoent
  571.  
  572.    NAME
  573.     endprotoent -- Closes the protocols file.
  574.  
  575.    SYNOPSIS
  576.     endprotoent ()
  577.  
  578.     void endprotoent (void);
  579.  
  580.    FUNCTION
  581.     Closes the protocols file if it is open.  This function is needed
  582.     only if getprotoent() or setprotoent() have been called.
  583.  
  584.    INPUTS
  585.     None.
  586.  
  587.    RESULT
  588.     None.
  589.  
  590.    EXAMPLE
  591.  
  592.    NOTES
  593.  
  594.    BUGS
  595.  
  596.    SEE ALSO
  597.     getprotoent(), setprotoent(), getprotobyname(), getprotobynumber()
  598.  
  599. socket.library/endpwent                               socket.library/endpwent
  600.  
  601.    NAME
  602.     endpwent - Closes the password file.
  603.  
  604.    SYNOPSIS
  605.     endpwent ()
  606.  
  607.     void endpwent (void);
  608.  
  609.    FUNCTION
  610.     Closes the password file if it was open. Reset the 'flag'
  611.     which may have been set by setpwent().
  612.  
  613.    INPUTS
  614.     None.
  615.  
  616.    RESULT
  617.     None.
  618.  
  619.    SEE ALSO
  620.     getpwent(), setpwent()
  621.  
  622. socket.library/endservent                           socket.library/endservent
  623.  
  624.    NAME
  625.     endservent -- Closes the services file.
  626.  
  627.    SYNOPSIS
  628.     endservent ()
  629.  
  630.     void endservent (void);
  631.  
  632.    FUNCTION
  633.     Closes the services file if it is open.  This function is needed
  634.     only if setservent() or getservent() have been called.
  635.  
  636.    INPUTS
  637.     None.
  638.  
  639.    RESULT
  640.     None.
  641.  
  642.    EXAMPLE
  643.  
  644.    NOTES
  645.  
  646.    BUGS
  647.  
  648.    SEE ALSO
  649.     setservent(), getservent()
  650.  
  651. socket.library/FD_SET                                   socket.library/FD_SET
  652.    NAME
  653.     FD_SET -- Macros to manipulate socket masks.
  654.  
  655.    SYNOPSIS
  656.     #include <sys/types.h>
  657.  
  658.     FD_SET(socket, mask)
  659.     FD_CLR(socket, mask)
  660.     result = FD_ISSET(socket, mask)
  661.     FD_ZERO(mask)
  662.  
  663.    FUNCTION
  664.     Type fd_set contains masks for use with sockets and select() just
  665.     like longs can contain masks for use with signals and Wait().
  666.     Unlike signal masks, you can't manipulate socket masks with boolean
  667.     operators, instead you must use the FD_*() macros.
  668.  
  669.     FD_SET() sets the "bit" for 'socket' in 'mask.'
  670.  
  671.  
  672.     FD_CLR() clears the "bit" for 'socket' in 'mask.'
  673.  
  674.     FD_ISSET() returns non-zero if the "bit" for 'socket' in 'mask' is
  675.     set, else zero.
  676.  
  677.     FD_ZERO() clears all "bits" in 'mask.'  FD_ZERO should be used
  678.     to initialize an fd_set variable before it is used.
  679.  
  680.    EXAMPLE
  681.  
  682.    SEE ALSO
  683.     select(), selectwait()
  684.  
  685. socket.library/getdomainname                     socket.library/getdomainname
  686.  
  687.    NAME
  688.     getdomainname -- Get domain name.
  689.  
  690.    SYNOPSIS
  691.     return = getdomainname (name, namelen)
  692.     D0            A1    D1
  693.  
  694.     int getdomainname (char *, int);
  695.  
  696.    FUNCTION
  697.     Returns the name of the domain into the pointer specified.
  698.     Name will be null-terminated if sufficient space is available.
  699.     To find out what a domain name is, check your favorite TCP/IP
  700.     reference.
  701.  
  702.    INPUTS
  703.     name        - pointer to character buffer.
  704.     namelen     - space available in 'name.'
  705.  
  706.    RESULT
  707.     0 is returned if successful.  -1 is returned on error.
  708.  
  709.    EXAMPLE
  710.  
  711.    NOTES
  712.     There is currently no corresponding setdomainname() function.
  713.  
  714.     Currently, configuration information is stored in memory in a
  715.     configuration structure.  This structure is initialized when
  716.     the network functions are started, and the data comes from
  717.     "INet:s/inet.config".
  718.  
  719.    BUGS
  720.  
  721.    SEE ALSO
  722.  
  723. socket.library/getgid                                   socket.library/getgid
  724.  
  725.    NAME
  726.     getgid -- Get group id.
  727.  
  728.    SYNOPSIS
  729.     #include <sys/types.h>
  730.  
  731.     gid = getgid ()
  732.     D0
  733.  
  734.     gid_t getgid (void);
  735.  
  736.    FUNCTION
  737.     returns the user's group id
  738.  
  739.    INPUTS
  740.     None.
  741.  
  742.    RESULT
  743.     gid        - group ID or -1 (on error).
  744.  
  745.    EXAMPLE
  746.  
  747.    NOTES
  748.     This is an emulation of the Unix getgid() function. The Unix
  749.     getegid() is equivalent to getgid() on the Amiga.  Note that the
  750.     user has one primary group ID, but may have several additional
  751.     secondary group IDs which can only be obtained with getgroups().
  752.  
  753.     Currently, configuration information is stored in memory in a
  754.     configuration structure.  This structure is initialized when
  755.     the network functions are started, and the data comes from
  756.     "INet:s/inet.config".
  757.  
  758.    BUGS
  759.  
  760.    SEE ALSO
  761.     getgroups(), getuid()
  762.  
  763. socket.library/getgrent                               socket.library/getgrent
  764.  
  765.    NAME
  766.     getgrent -- Read the next line in the group file.
  767.  
  768.    SYNOPSIS
  769.     group = getgrent ()
  770.     D0
  771.  
  772.     struct group *getgrent (void);
  773.  
  774.    FUNCTION
  775.     There is usually no reason to call this function directly.  It
  776.     is called internally by getgrgid() and getgrnam().  It is provided
  777.     only for Un*x compatibility.
  778.  
  779.     Opens the group file if necessary.  Returns the next entry
  780.     in the file in a group structure.
  781.  
  782.    INPUTS
  783.     None.
  784.  
  785.    RESULT
  786.     group        - a pointer to a filled in group structure
  787.               if successful, else NULL.
  788.  
  789.         struct group {
  790.             char    *gr_name;
  791.             char    *gr_passwd;
  792.             char    *gr_gecos;
  793.             gid_t    gr_gid;
  794.             char    **gr_mem;
  795.         };
  796.  
  797.    NOTES
  798.  
  799.     I-Net 225 ONLY.
  800.  
  801.    SEE ALSO
  802.     getgrgid(), getgrnam(), setgrent(), endgrent()
  803.  
  804. socket.library/getgrgid                               socket.library/getgrgid
  805.  
  806.    NAME
  807.     getgrgid -- Search group database for a particular gid.
  808.  
  809.    SYNOPSIS
  810.     #include <grp.h>
  811.  
  812.     passwd = getgrgid (gid)
  813.     D0           D1
  814.  
  815.     struct group *getgrgid (gid_t);
  816.  
  817.    FUNCTION
  818.     getgrgid() returns a pointer to a group structure.  The group
  819.     structure fields are filled in from the fields contained in
  820.     one line of the group file.
  821.  
  822.    INPUTS
  823.     gid        - gid of group entry to look up.
  824.  
  825.    RESULT
  826.     group        - a pointer to a group struct with its elements
  827.               filled in from the group file.
  828.  
  829.         struct group {
  830.             char    *gr_name;
  831.             char    *gr_passwd;
  832.             char    *gr_gecos;
  833.             gid_t    gr_gid;
  834.             char    **gr_mem;
  835.         };
  836.  
  837.    NOTES
  838.     The group structure is returned in a buffer that will be
  839.     overwritten on the next call to getgr*().
  840.  
  841.     I-Net 225 ONLY.
  842.  
  843.    SEE ALSO
  844.     getgrnam()
  845.  
  846. socket.library/getgrnam                               socket.library/getgrnam
  847.  
  848.    NAME
  849.     getgrnam -- Search group database for a particular name.
  850.  
  851.    SYNOPSIS
  852.     #include <grp.h>
  853.  
  854.     group = getgrnam (name)
  855.     D0            A0
  856.  
  857.     struct group *getgrnam (char *);
  858.  
  859.    FUNCTION
  860.     getgrnam() returns a pointer to a group structure. The group
  861.     structure fields are filled in from the fields contained in
  862.     one line of the group file.
  863.  
  864.    INPUTS
  865.     name        - group name of group entry to look up.
  866.  
  867.    RESULT
  868.     group        - a pointer to a group struct with its elements
  869.               filled in from the group file.
  870.  
  871.         struct group {
  872.             char    *gr_name;
  873.             char    *gr_passwd;
  874.             char    *gr_gecos;
  875.             gid_t    gr_gid;
  876.             char    **gr_mem;
  877.         };
  878.  
  879.    NOTES
  880.     The group structure is returned in a buffer that will be
  881.     overwritten on the next call to getgr*().
  882.  
  883.     I-Net 225 ONLY.
  884.  
  885.    SEE ALSO
  886.     getgrgid()
  887. socket.library/getgroups                             socket.library/getgroups
  888.  
  889.    NAME
  890.     getgroups -- Get group access list.
  891.  
  892.    SYNOPSIS
  893.     #include <sys/types.h>
  894.     #include <sys/param.h>
  895.  
  896.     num = getgroups (max_gids, gids)
  897.     D0         D0       A0
  898.  
  899.     int getgroups (int, gid_t *);
  900.  
  901.    FUNCTION
  902.     The array "gids" is filled with the group ids that the current user
  903.     belongs to (including the primary gid).  The list may be up to
  904.     "max_gids" long.  The actual number of gids is returned in 'num.'
  905.  
  906.    INPUTS
  907.     max_gids    - length of gids array.
  908.     gids        - gid_t array.
  909.  
  910.    RESULT
  911.     num        - the number of gids is returned if successful.
  912.               No errors are currently defined.
  913.  
  914.    EXAMPLE
  915.     gid_t gids [8];
  916.     int number_of_gids;
  917.  
  918.     number_of_gids = getgroups (8, gids);
  919.  
  920.    NOTES
  921.     Currently, configuration information is stored in memory in a
  922.     configuration structure.  This structure is initialized when
  923.     the network functions are started, and the data comes from
  924.     "INet:s/inet.config".
  925.  
  926.     The upper limit of groups that can be returned by getgroups() is
  927.     NGROUP (in <sys/param.h>).
  928.  
  929.    BUGS
  930.     This routine has had problems including the primary gid.
  931.     These problems should be fixed, so please report if you
  932.     see this bug.
  933.  
  934.    SEE ALSO
  935.     getgid(), getuid()
  936.  
  937. socket.library/gethostbyaddr                     socket.library/gethostbyaddr
  938.  
  939.    NAME
  940.     gethostbyaddr -- Get host entry from the hosts file.
  941.  
  942.    SYNOPSIS
  943.     #include <sys/socket.h>
  944.     #include <netdb.h>
  945.  
  946.     host = gethostbyaddr (addr, len, type )
  947.     D0              A0    D0     D1
  948.  
  949.     struct hostent *gethostbyaddr (char *, int, int);
  950.  
  951.    FUNCTION
  952.     Opens the host file if necessary.  Finds the entry for 'addr'
  953.     and returns it in a hostent structure.    If "usedns=true" is set
  954.     in INet:s/inet.config, and INet:db/resolv.conf is set up, then
  955.     a DNS request will be made for the information, if it is not
  956.     present in the hosts file.
  957.  
  958.     struct    hostent {
  959.         char    *h_name;        /* official name of host */
  960.         char    **h_aliases;    /* alias list */
  961.         int     h_addrtype;     /* host address type */
  962.         int     h_length;        /* length of address */
  963.         char    **h_addr_list;  /* list of addresses from name server */
  964.     #define h_addr    h_addr_list[0]    /* messed up for historical reasons */
  965.     };
  966.  
  967.    INPUTS
  968.     addr        - internet address, in network byte order.
  969.               (This is really a long.)
  970.     len        - sizeof(addr), usually 4
  971.     type        - usually AF_INET
  972.  
  973.    RESULT
  974.     host        - pointer to struct hostent for host 'addr.'
  975.               NULL on EOF or failure to open hosts file.
  976.  
  977.    EXAMPLE
  978.  
  979.    NOTES
  980.     The only type currently in use is AF_INET.
  981.  
  982.     The buffer pointed to by 'host' will be overwritten by the next
  983.     call to gethost*().
  984.  
  985.    BUGS
  986.  
  987.    SEE ALSO
  988.     gethostbyname()
  989.  
  990. socket.library/gethostbyname                     socket.library/gethostbyname
  991.  
  992.    NAME
  993.     gethostbyname -- Get host entry from the hosts file.
  994.  
  995.    SYNOPSIS
  996.     #include <sys/socket.h>
  997.     #include <netdb.h>
  998.  
  999.     host = gethostbyname (name)
  1000.     D0              A0
  1001.  
  1002.     struct hostent *gethostbyname (char *);
  1003.  
  1004.    FUNCTION
  1005.     Opens the host file if necessary.  Finds the entry for "name"
  1006.     and returns it in a hostent structure. If "usedns=true" is set
  1007.     in INet:s/inet.config, and INet:db/resolv.conf is set up, then
  1008.     a DNS request will be made for the information, if it is not
  1009.     present in the hosts file.
  1010.  
  1011.     struct    hostent {
  1012.         char    *h_name;        /* official name of host */
  1013.         char    **h_aliases;    /* alias list */
  1014.         int     h_addrtype;     /* host address type */
  1015.         int     h_length;        /* length of address */
  1016.         char    **h_addr_list;  /* list of addresses from name server */
  1017.     #define h_addr    h_addr_list[0] /* messed up for historical reasons */
  1018.     };
  1019.  
  1020.    INPUTS
  1021.  
  1022.    RESULT
  1023.     host        - pointer to struct hostent for host 'name.'
  1024.               NULL on EOF or failure to open hosts file.
  1025.  
  1026.    EXAMPLE
  1027.  
  1028.    NOTES
  1029.     The buffer pointed to by 'host' will be overwritten by the next
  1030.     call to gethost*().
  1031.  
  1032.    BUGS
  1033.  
  1034.    SEE ALSO
  1035.     gethostbyaddr()
  1036.  
  1037. socket.library/gethostent                           socket.library/gethostent
  1038.  
  1039.    NAME
  1040.     gethostent -- Get host entry from the hosts file ("INet:db/hosts").
  1041.  
  1042.    SYNOPSIS
  1043.     #include <sys/types.h>
  1044.     #include <sys/socket.h>
  1045.     #include <netdb.h>
  1046.  
  1047.     host = gethostent ()
  1048.     D0
  1049.  
  1050.     struct hostent *gethostent (void);
  1051.  
  1052.    FUNCTION
  1053.     There is normally no reason to use this function.  It is used
  1054.     internally by gethostbyname() and gethostbyaddr().  It is provided
  1055.     only for Unix compatibility and even Unix is phasing it out in
  1056.     favor of other methods of name resolution.
  1057.  
  1058.     Opens the host file if necessary.  Returns the next entry
  1059.     in the file in a hostent structure.
  1060.  
  1061.     struct    hostent {
  1062.         char    *h_name;        /* official name of host */
  1063.         char    **h_aliases;    /* alias list */
  1064.         int     h_addrtype;     /* host address type */
  1065.         int     h_length;        /* length of address */
  1066.         char    **h_addr_list;  /* list of addresses from name server */
  1067.     #define h_addr    h_addr_list[0] /* messed up for historical reasons */
  1068.     };
  1069.  
  1070.    INPUTS
  1071.     None.
  1072.  
  1073.    RESULT
  1074.     host        - pointer to struct hostent
  1075.               NULL on EOF or failure to open host file.
  1076.    EXAMPLE
  1077.  
  1078.    NOTES
  1079.     The buffer pointed to by 'host' will be overwritten by the next
  1080.     call to gethost*().
  1081.  
  1082.    BUGS
  1083.  
  1084.    SEE ALSO
  1085.     sethostent(), gethostbyname(), gethostbyaddr(), endhostent()
  1086.  
  1087. socket.library/gethostname                         socket.library/gethostname
  1088.  
  1089.    NAME
  1090.     gethostname -- Get the name of your Amiga.
  1091.  
  1092.    SYNOPSIS
  1093.     return = gethostname (name, length)
  1094.     D0              A0    D0
  1095.  
  1096.     int gethostname (char *, int);
  1097.  
  1098.    FUNCTION
  1099.     Copies the  null-terminated hostname to 'name'.  The hostname will
  1100.     be truncated if insufficient space is available in 'name'.
  1101.  
  1102.    INPUTS
  1103.     name        - pointer to a character array.
  1104.     length        - size of the character array.
  1105.  
  1106.    RESULT
  1107.     return        - 0 if successful, else -1.
  1108.  
  1109.    NOTES
  1110.     Currently, configuration information is stored in memory in a
  1111.     configuration structure.  This structure is initialized when
  1112.     the network functions are started, and the data comes from
  1113.     "INet:s/inet.config".
  1114.  
  1115.    BUGS
  1116.  
  1117.    SEE ALSO
  1118.  
  1119. socket.library/getlogin                               socket.library/getlogin
  1120.  
  1121.    NAME
  1122.     getlogin -- Get login name.
  1123.  
  1124.    SYNOPSIS
  1125.     name = getlogin ()
  1126.     D0
  1127.  
  1128.     char *getlogin (void);
  1129.  
  1130.    FUNCTION
  1131.     Returns a pointer to the current user name.
  1132.  
  1133.    INPUTS
  1134.     None.
  1135.  
  1136.    RESULT
  1137.     name        - a pointer to the current user name or NULL to
  1138.               indicate an error.  You can use this pointer for
  1139.               as long as necessary, but do not write to it.
  1140.  
  1141.    NOTES
  1142.     Currently, configuration information is stored in memory in a
  1143.     configuration structure.  This structure is initialized when
  1144.     the network functions are started, and the data comes from
  1145.     "INet:s/inet.config". There is no support for multiple user
  1146.     IDs on a single Amiga because the Amiga OS has no concept of
  1147.     multiple users.
  1148.  
  1149.  
  1150. socket.library/getnetbyaddr                       socket.library/getnetbyaddr
  1151.  
  1152.    NAME
  1153.     getnetbyaddr -- Get net entry from the networks file.
  1154.  
  1155.    SYNOPSIS
  1156.     #include <netdb.h>
  1157.  
  1158.     net = getnetbyaddr (net, type )
  1159.     D0            D0     D1
  1160.  
  1161.     struct netent *getnetbyaddr (long, int);
  1162.  
  1163.    FUNCTION
  1164.     Opens the networks file if necessary.  Returns the entry
  1165.     with a matching address in a nettent structure.
  1166.  
  1167.     struct    netent {
  1168.         char        *n_name;    /* official name of net */
  1169.         char        **n_aliases;    /* alias list */
  1170.         int        n_addrtype;    /* net address type */
  1171.         unsigned long    n_net;        /* network # */
  1172.     };
  1173.  
  1174.    INPUTS
  1175.     net        - network number.
  1176.     type        - network number type, currently AF_INET.
  1177.  
  1178.    RESULT
  1179.     net        - netent structure if succesful, NULL on EOF on
  1180.               failure to open networks file.
  1181.  
  1182.    EXAMPLE
  1183.  
  1184.    NOTES
  1185.     The netent structure is returned in a buffer that will be
  1186.     overwritten on the next call to getnet*().
  1187.  
  1188.    BUGS
  1189.  
  1190.    SEE ALSO
  1191.     getnetbyname()
  1192.  
  1193. socket.library/getnetbyname                       socket.library/getnetbyname
  1194.  
  1195.    NAME
  1196.     getnetbyname -- Get net entry from the networks file.
  1197.  
  1198.    SYNOPSIS
  1199.     #include <netdb.h>
  1200.  
  1201.     net = getnetbyname (name)
  1202.     D0            A0
  1203.  
  1204.     struct netent *getnetbyname (char *);
  1205.  
  1206.    FUNCTION
  1207.     Opens the networks file if necessary.  Returns the entry
  1208.     with a matching name in a nettent structure.
  1209.  
  1210.     struct    netent {
  1211.         char        *n_name;    /* official name of net */
  1212.         char        **n_aliases;    /* alias list */
  1213.         int        n_addrtype;    /* net address type */
  1214.         unsigned long    n_net;        /* network # */
  1215.     };
  1216.  
  1217.    INPUTS
  1218.     name        - network name.
  1219.  
  1220.    RESULT
  1221.     net        - netent structure if succesful, NULL on EOF on
  1222.               failure to open networks file.
  1223.  
  1224.    EXAMPLE
  1225.  
  1226.    NOTES
  1227.     The netent structure is returned in a buffer that will be
  1228.     overwritten on the next call to getnet*().
  1229.  
  1230.    BUGS
  1231.  
  1232.    SEE ALSO
  1233.     getnetbyaddr()
  1234.  
  1235. socket.library/getnetent                             socket.library/getnetent
  1236.  
  1237.    NAME
  1238.     getnetent -- Get net entry from the networks file.
  1239.  
  1240.    SYNOPSIS
  1241.     #include <netdb.h>
  1242.  
  1243.     net = getnetent ()
  1244.     D0
  1245.  
  1246.     struct netent *getnetent (void);
  1247.  
  1248.    FUNCTION
  1249.     This function should not normally be used.  It is called internally
  1250.     by getnetbyname() and getnetbyaddr().
  1251.  
  1252.     Opens the networks file if necessary.  Returns the next entry
  1253.     in the file in a nettent structure.
  1254.  
  1255.     struct    netent {
  1256.         char        *n_name;    /* official name of net */
  1257.         char        **n_aliases;    /* alias list */
  1258.         int        n_addrtype;    /* net address type */
  1259.         unsigned long    n_net;        /* network # */
  1260.     };
  1261.  
  1262.    INPUTS
  1263.     None.
  1264.  
  1265.    RESULT
  1266.     net        - netent structure if succesful, NULL on EOF on
  1267.               failure to open networks file.
  1268.  
  1269.    EXAMPLE
  1270.  
  1271.    NOTES
  1272.     The netent structure is returned in a buffer that will be
  1273.     overwritten on the next call to getnet*().
  1274.  
  1275.    BUGS
  1276.  
  1277.    SEE ALSO
  1278.     setnetent(), getnetbyname(), getnetbyaddr(), endnetent()
  1279.  
  1280. socket.library/getpeername                         socket.library/getpeername
  1281.  
  1282.    NAME
  1283.     getpeername -- Get name of connected peer.
  1284.  
  1285.    SYNOPSIS
  1286.     return = getpeername (s, name, namelen)
  1287.     D0              D0 A0    A1
  1288.  
  1289.     int getpeername (int, struct sockaddr *, int *);
  1290.  
  1291.    FUNCTION
  1292.     For every connected socket, there is a socket at the other end
  1293.     of the connection.  To determine the address of the socket at the
  1294.     other end of a connection, pass getpeername() the socket on your
  1295.     end.  'Namelen' should be initialized to the amount of space pointed
  1296.     to by 'name.'  The actual size of 'name' will be returned in
  1297.     'namelen.'
  1298.  
  1299.    INPUTS
  1300.     s        - socket descriptor.
  1301.     name        - pointer to a struct sockaddr.
  1302.     namelen     - initialized to size of 'name.' On return this
  1303.               contains the actual sizeof(name)
  1304.  
  1305.    RESULT
  1306.     return        - 0 if successful else -1 (errno will contain the
  1307.               specific error).
  1308.  
  1309.    EXAMPLE
  1310.  
  1311.    NOTES
  1312.  
  1313.    BUGS
  1314.  
  1315.    SEE ALSO
  1316.     bind(), accept(), getsockname()
  1317.  
  1318. socket.library/getprotobyname                   socket.library/getprotobyname
  1319.  
  1320.    NAME
  1321.     getprotobyname -- find a protocol entry by name
  1322.  
  1323.    SYNOPSIS
  1324.     #include <netdb.h>
  1325.  
  1326.     proto = getprotobyname (name)
  1327.     D0            A0
  1328.  
  1329.     struct protoent *getprotobyname (char *);
  1330.  
  1331.    FUNCTION
  1332.     Opens the protocols file if necessary.    Returns the entry
  1333.     with a matching name in a protoent structure.
  1334.  
  1335.     struct    protoent {
  1336.         char    *p_name;    /* official protocol name */
  1337.         char    **p_aliases;    /* alias list */
  1338.         int    p_proto;    /* protocol # */
  1339.     };
  1340.  
  1341.  
  1342.    INPUTS
  1343.     name        - name of prototype to return.
  1344.  
  1345.    RESULT
  1346.     proto        - pointer to struct protoent for protocol 'name.'
  1347.               NULL on EOF or failure to open protocols file.
  1348.  
  1349.    EXAMPLE
  1350.  
  1351.    NOTES
  1352.     The protoent structure is returned in a buffer that will be
  1353.     overwritten on the next call to getproto*()
  1354.  
  1355.    BUGS
  1356.  
  1357.    SEE ALSO
  1358.     getprotobynumber()
  1359.  
  1360. socket.library/getprotobynumber               socket.library/getprotobynumber
  1361.  
  1362.    NAME
  1363.     getprotobynumber -- find a protocol entry by number
  1364.  
  1365.    SYNOPSIS
  1366.     #include <netdb.h>
  1367.  
  1368.     proto = getprotobynumber (proto)
  1369.     D0              D0
  1370.  
  1371.     struct protoent *getprotobynumber (int);
  1372.  
  1373.    FUNCTION
  1374.     Opens the protocols file if necessary.    Returns the entry
  1375.     with a matching protocol number in a protoent structure.
  1376.  
  1377.     struct    protoent {
  1378.         char    *p_name;    /* official protocol name */
  1379.         char    **p_aliases;    /* alias list */
  1380.         int    p_proto;    /* protocol # */
  1381.     };
  1382.  
  1383.  
  1384.    INPUTS
  1385.     proto        - number of prototype to return.
  1386.  
  1387.    RESULT
  1388.     proto        - pointer to struct protoent for protocol 'number.'
  1389.               NULL on EOF or failure to open protocols file.
  1390.  
  1391.    EXAMPLE
  1392.  
  1393.    NOTES
  1394.     The protoent structure is returned in a buffer that will be
  1395.     overwritten on the next call to getproto*()
  1396.  
  1397.    BUGS
  1398.  
  1399.    SEE ALSO
  1400.     getprotobyname()
  1401.  
  1402. socket.library/getprotoent                         socket.library/getprotoent
  1403.  
  1404.    NAME
  1405.     getprotoent -- Get a protocol entry from the protocols file.
  1406.  
  1407.    SYNOPSIS
  1408.     #include <netdb.h>
  1409.  
  1410.     proto = getprotoent ()
  1411.  
  1412.     struct protoent *getprotoent (void);
  1413.  
  1414.    FUNCTION
  1415.     There is normally no reason to use this function.  It is used
  1416.     internally by getprotobyname() and getprotobynumber().    It is
  1417.     provided only for Unix compatibility.
  1418.  
  1419.     Opens the protocols file if necessary.    Returns the next entry
  1420.     in the file in a protoent structure.
  1421.  
  1422.     struct    protoent {
  1423.         char    *p_name;    /* official protocol name */
  1424.         char    **p_aliases;    /* alias list */
  1425.         int    p_proto;    /* protocol # */
  1426.     };
  1427.  
  1428.  
  1429.    INPUTS
  1430.     None.
  1431.  
  1432.    RESULT
  1433.     proto        - NULL on EOF or failure to open protocols file.
  1434.  
  1435.    EXAMPLE
  1436.  
  1437.    NOTES
  1438.     The protoent structure is returned in a buffer that will be
  1439.     overwritten on the next call to getproto*()
  1440.  
  1441.    BUGS
  1442.  
  1443.    SEE ALSO
  1444.     getprotobyname(), getprotobynumber(), setprotoent(), endprotoent()
  1445.  
  1446. socket.library/getpwent                               socket.library/getpwent
  1447.  
  1448.    NAME
  1449.     getpwent -- Read the next line in the password file.
  1450.  
  1451.    SYNOPSIS
  1452.     passwd = getpwent ()
  1453.     D0
  1454.  
  1455.     struct passwd *getpwent (void);
  1456.  
  1457.    FUNCTION
  1458.     There is usually no reason to call this function directly.  It
  1459.     is called internally by getpwuid() and getpwnam().  It is provided
  1460.     only for Un*x compatibility.
  1461.  
  1462.     Opens the password file if necessary.  Returns the next entry
  1463.     in the file in a passwd structure, or NULL if at EOF.
  1464.  
  1465.     struct passwd {
  1466.         char    *pw_name;
  1467.         char    *pw_dir;
  1468.         char    *pw_passwd;
  1469.         char    *pw_gecos;
  1470.         uid_t    pw_uid;
  1471.         gid_t    pw_gid;
  1472.         char    *pw_shell;        /* currently unused */
  1473.         char    *pw_comment;
  1474.     };
  1475.  
  1476.    INPUTS
  1477.     None.
  1478.  
  1479.    RESULT
  1480.     passwd        - a pointer to a filled in passwd structure
  1481.               if successful, else NULL.
  1482.  
  1483.    SEE ALSO
  1484.     getpwuid(), getpwnam(), setpwent(), endpwent()
  1485.  
  1486. socket.library/getpwnam                               socket.library/getpwnam
  1487.  
  1488.    NAME
  1489.     getpwnam -- Search user database for a particular name.
  1490.  
  1491.    SYNOPSIS
  1492.     #include <pwd.h>
  1493.  
  1494.     passwd = getpwnam (name)
  1495.     D0           A0
  1496.  
  1497.     struct passwd *getpwnam (char *);
  1498.  
  1499.    FUNCTION
  1500.     getpwnam() returns a pointer to a passwd structure. The passwd
  1501.     structure fields are filled in from the fields contained in
  1502.     one line of the password file.
  1503.  
  1504.    INPUTS
  1505.     name        - user name of passwd entry to look up.
  1506.  
  1507.    RESULT
  1508.     passwd        - a pointer to a passwd struct with its elements
  1509.               filled in from the passwd file, or NULL if it
  1510.               cannot be found for this name.
  1511.  
  1512.         struct passwd {
  1513.             char    *pw_name;
  1514.             char    *pw_dir;
  1515.             char    *pw_passwd;
  1516.             char    *pw_gecos;
  1517.             uid_t    pw_uid;
  1518.             gid_t    pw_gid;
  1519.             char    *pw_shell;    /* currently unused  */
  1520.             char    *pw_comment;
  1521.         };
  1522.  
  1523.    NOTES
  1524.     The passwd structure is returned in a buffer that will be
  1525.     overwritten on the next call to getpw*().
  1526.  
  1527.    SEE ALSO
  1528.     getpwuid()
  1529. socket.library/getpwuid                               socket.library/getpwuid
  1530.  
  1531.    NAME
  1532.     getpwuid -- Search user database for a particular uid.
  1533.  
  1534.    SYNOPSIS
  1535.     #include <pwd.h>
  1536.  
  1537.     passwd = getpwuid (uid)
  1538.     D0           D1
  1539.  
  1540.     struct passwd *getpwuid (uid_t);
  1541.  
  1542.    FUNCTION
  1543.     getpwuid() returns a pointer to a passwd structure.  The passwd
  1544.     structure fields are filled in from the fields contained in
  1545.     one line of the password file.
  1546.  
  1547.    INPUTS
  1548.     uid        - uid of passwd entry to look up.
  1549.  
  1550.    RESULT
  1551.     passwd        - a pointer to a passwd struct with its elements
  1552.               filled in from the passwd file, or NULL if it
  1553.               cannot be found for this uid.
  1554.  
  1555.         struct passwd {
  1556.             char    *pw_name;
  1557.             char    *pw_dir;
  1558.             char    *pw_passwd;
  1559.             char    *pw_gecos;
  1560.             uid_t    pw_uid;
  1561.             gid_t    pw_gid;
  1562.             char    *pw_shell;    /* currently unused */
  1563.             char    *pw_comment;
  1564.         };
  1565.  
  1566.    NOTES
  1567.     The passwd structure is returned in a buffer that will be
  1568.     overwritten on the next call to getpw*().
  1569.  
  1570.    SEE ALSO
  1571.     getpwnam()
  1572.  
  1573. socket.library/getservbyname                     socket.library/getservbyname
  1574.  
  1575.    NAME
  1576.     getservbyname -- Find a service entry by name.
  1577.  
  1578.    SYNOPSIS
  1579.     #include <netdb.h>
  1580.  
  1581.     serv = getservbyname (name, proto)
  1582.     D0              A0    A1
  1583.  
  1584.     struct servent *getservbyname (char *, char *);
  1585.  
  1586.    FUNCTION
  1587.     Opens the services file and finds the service with the matching
  1588.     name and protocol.
  1589.  
  1590.     struct    servent {
  1591.         char    *s_name;    /* official service name */
  1592.         char    **s_aliases;    /* alias list */
  1593.         int    s_port;     /* port # */
  1594.         char    *s_proto;    /* protocol to use */
  1595.     };
  1596.  
  1597.  
  1598.    INPUTS
  1599.     name        - name of service to look up.
  1600.     proto        - protocol of service to look up.
  1601.  
  1602.    RESULT
  1603.     serv        - pointer to struct servent for service 'name.'
  1604.               NULL on EOF or failure to open protocols file.
  1605.  
  1606.    EXAMPLE
  1607.  
  1608.    NOTES
  1609.     The servent structure is returned in a buffer that will be
  1610.     overwritten on the next call to getserv*().
  1611.  
  1612.    BUGS
  1613.  
  1614.    SEE ALSO
  1615.     getservent(), getservbyport()
  1616.  
  1617. socket.library/getservbyport                     socket.library/getservbyport
  1618.  
  1619.    NAME
  1620.     getservbyport -- Find a service entry by port.
  1621.  
  1622.    SYNOPSIS
  1623.     #include <netdb.h>
  1624.  
  1625.     serv = getservbyport (port, proto)
  1626.     D0              D0    A0
  1627.  
  1628.     struct servent *getservbyport (u_short, char *);
  1629.  
  1630.    FUNCTION
  1631.     Opens the services file and finds the service with the matching
  1632.     port and protocol.
  1633.  
  1634.     struct    servent {
  1635.         char    *s_name;    /* official service name */
  1636.         char    **s_aliases;    /* alias list */
  1637.         int    s_port;     /* port # */
  1638.         char    *s_proto;    /* protocol to use */
  1639.     };
  1640.  
  1641.    INPUTS
  1642.  
  1643.    RESULT
  1644.     serv        - pointer to struct servent for service 'name.'
  1645.               NULL on EOF or failure to open protocols file.
  1646.  
  1647.    EXAMPLE
  1648.  
  1649.    NOTES
  1650.     The servent structure is returned in a buffer that will be
  1651.     overwritten on the next call to getserv*().
  1652.  
  1653.    BUGS
  1654.  
  1655.    SEE ALSO
  1656.     getservent(), getservbyname()
  1657.  
  1658. socket.library/getservent                           socket.library/getservent
  1659.  
  1660.    NAME
  1661.     getservent -- Get a service entry from the services file.
  1662.  
  1663.    SYNOPSIS
  1664.     #include <netdb.h>
  1665.  
  1666.     serv = getservent (void)
  1667.     D0
  1668.  
  1669.     struct servent *getservent (void);
  1670.  
  1671.    FUNCTION
  1672.     There is normally no reason to use this function.  It is used
  1673.     internally by getservbyname() and getservbyport().  It is
  1674.     provided only for Unix compatibility.
  1675.  
  1676.     Opens the services file if necessary.  Returns the next entry
  1677.     in the file in a servent structure.
  1678.  
  1679.     struct    servent {
  1680.         char    *s_name;    /* official service name */
  1681.         char    **s_aliases;    /* alias list */
  1682.         int    s_port;     /* port # */
  1683.         char    *s_proto;    /* protocol to use */
  1684.     };
  1685.  
  1686.    INPUTS
  1687.     None.
  1688.  
  1689.    RESULT
  1690.     serv        - pointer to struct servent for next service.
  1691.               NULL on EOF or failure to open protocols file.
  1692.  
  1693.    EXAMPLE
  1694.  
  1695.    NOTES
  1696.     The servent structure is returned in a buffer that will be
  1697.     overwritten on the next call to getserv*()
  1698.  
  1699.    BUGS
  1700.  
  1701.    SEE ALSO
  1702.     setservent(), getservbyname(), getservbyport(), endservent()
  1703.  
  1704. socket.library/getsockname                         socket.library/getsockname
  1705.  
  1706.    NAME
  1707.     getsockname -- Get the name of a socket.
  1708.  
  1709.    SYNOPSIS
  1710.     return = getsockname (s, name, namelen)
  1711.     D0              D0 A0    A1
  1712.  
  1713.     int getsockname (int, struct sockaddr *, int *);
  1714.  
  1715.    FUNCTION
  1716.     Returns the name (address) of the specified socket.  'Namelen'
  1717.     should be initialized to the amount of space pointed to by 'name.'
  1718.     The actual size of 'name' will be returned in 'namelen.'
  1719.  
  1720.    INPUTS
  1721.     s        - socket descriptor.
  1722.     name        - socket name.
  1723.     namelen     - size of 'name' (in bytes).
  1724.  
  1725.    RESULT
  1726.     return        - 0 if successful else -1 (errno will be set to
  1727.               one of the following error codes:
  1728.               EBADF     invalid socket
  1729.  
  1730.    EXAMPLE
  1731.  
  1732.    NOTES
  1733.  
  1734.    BUGS
  1735.  
  1736.    SEE ALSO
  1737.     bind(), getpeername()
  1738.  
  1739. socket.library/getsockopt                           socket.library/getsockopt
  1740.  
  1741.    NAME
  1742.     getsockopt -- Get socket options.
  1743.  
  1744.    SYNOPSIS
  1745.     return = getsockopt (s, level, optname, optval, optlenp)
  1746.     D0             D0 D1     D2    A0    A1
  1747.  
  1748.     int getsockopt (int, int, int, char *, int *);
  1749.  
  1750.    FUNCTION
  1751.     Gets the option specified by 'optname' for socket 's.'
  1752.     This is an advanced function.  See the "sys/socket.h" header and
  1753.     your favorite TCP/IP reference for more information on options.
  1754.  
  1755.    INPUTS
  1756.     s        - socket descriptor.
  1757.     level        - protocol level.  Valid levels are:
  1758.               IPPROTO_IP           IP options
  1759.               IPPROTO_TCP           TCP options
  1760.               SOL_SOCKET           socket options
  1761.     optname     - option name.
  1762.     optval        - pointer to the buffer which will contain the
  1763.               answer.
  1764.     optlen        - initially sizeof(optval). reset to new value
  1765.               on return
  1766.  
  1767.    RESULT
  1768.     return        - 0 if successful else -1 (errno will contain the
  1769.               specific error).
  1770.  
  1771.    EXAMPLE
  1772.  
  1773.    NOTES
  1774.  
  1775.    BUGS
  1776.  
  1777.    SEE ALSO
  1778.     setsockopt()
  1779.  
  1780. socket.library/getuid                                   socket.library/getuid
  1781.  
  1782.    NAME
  1783.     getuid    -- Get user id.
  1784.  
  1785.    SYNOPSIS
  1786.     #include <sys/types.h>
  1787.  
  1788.     uid = getuid ()
  1789.     D0
  1790.  
  1791.     uid_t getuid (void);
  1792.  
  1793.    FUNCTION
  1794.     Returns the user id.
  1795.  
  1796.    INPUTS
  1797.     None.
  1798.  
  1799.    RESULT
  1800.     uid        - user ID or -1 (on error).
  1801.  
  1802.    EXAMPLE
  1803.  
  1804.    NOTES
  1805.     This is an emulation of the Unix getuid() function. The Unix
  1806.     geteuid() is equivalent to getuid() on the Amiga.
  1807.  
  1808.     Currently, configuration information is stored in memory in a
  1809.     configuration structure.  This structure is initialized when
  1810.     the network functions are started, and the data comes from
  1811.     "INet:s/inet.config". There is no support for multiple user
  1812.     IDs on a single Amiga because the Amiga OS has no concept of
  1813.     multiple users.
  1814.  
  1815.    BUGS
  1816.  
  1817.    SEE ALSO
  1818.     getgid(), getgroups()
  1819.  
  1820. socket.library/getumask                               socket.library/getumask
  1821.  
  1822.    NAME
  1823.     getumask -- Get user file creation mask.
  1824.  
  1825.    SYNOPSIS
  1826.     #include <sys/types.h>
  1827.  
  1828.     umask = getumask ()
  1829.     D0
  1830.  
  1831.     mode_t getumask (void);
  1832.  
  1833.    FUNCTION
  1834.     Returns the umask.
  1835.  
  1836.    RESULT
  1837.     -1 will be returned and an error message will be displayed
  1838.     if there is a problem reading the current configuration.
  1839.  
  1840.    EXAMPLE
  1841.  
  1842.    NOTES
  1843.     THIS IS AN AMIGA-SPECIFIC FUNCTION.  It is not a standard Unix
  1844.     function.  See umask().
  1845.  
  1846.     Currently, configuration information is stored in memory in a
  1847.     configuration structure.  This structure is initialized when
  1848.     the network functions are started, and the data comes from
  1849.     "INet:s/inet.config".
  1850.  
  1851.    BUGS
  1852.  
  1853.    SEE ALSO
  1854.     umask()
  1855.  
  1856. socket.library/get_tz                                   socket.library/get_tz
  1857.  
  1858.    NAME
  1859.     get_tz -- Get timezone offset.
  1860.  
  1861.    SYNOPSIS
  1862.     offset = get_tz ()
  1863.     D0
  1864.  
  1865.     short get_tz (void);
  1866.  
  1867.    FUNCTION
  1868.     Returns the number offset from UTC (Universal Time Coordinated,
  1869.     formerly Greenwich Mean Time) in minutes west of UTC.
  1870.  
  1871.    RESULT
  1872.     offset        - offset in minutes or -1.
  1873.  
  1874.    NOTES
  1875.     THIS IS AN AMIGA-ONLY FUNCTION.
  1876.  
  1877.     Currently, configuration information is stored in memory in a
  1878.     configuration structure.  This structure is initialized when
  1879.     the network functions are started, and the data comes from
  1880.     "INet:s/inet.config".
  1881.  
  1882.    BUGS
  1883.     Does not account for daylight savings time.  If the time is really
  1884.     important to you (or hosts you communicate with) you must currently
  1885.     change your INet:s/inet.config for daylight savings/standard time.
  1886.  
  1887. socket.library/inet_addr                             socket.library/inet_addr
  1888.  
  1889.    NAME
  1890.     inet_addr -- make internet address from string
  1891.  
  1892.    SYNOPSIS
  1893.     #include <sys/types.h>
  1894.     #include <sys/socket.h>
  1895.     #include <netinet/in.h>
  1896.  
  1897.     addr = inet_addr (string)
  1898.     D0          A1
  1899.  
  1900.     u_long inet_addr (char *);
  1901.  
  1902.    FUNCTION
  1903.     Converts a string to an internet address.  All internet addresses
  1904.     are in network order.
  1905.  
  1906.    INPUTS
  1907.     string        address string. "123.45.67.89" for example
  1908.  
  1909.    RESULT
  1910.     A long representing the network address in network byte order.
  1911.  
  1912.     INADDR_NONE is returned if input is invalid.
  1913.  
  1914.    EXAMPLE
  1915.  
  1916.    NOTES
  1917.  
  1918.    BUGS
  1919.  
  1920.    SEE ALSO
  1921.  
  1922. socket.library/inet_aton                             socket.library/inet_aton
  1923.  
  1924.    NAME
  1925.     inet_aton -- make internet address from string
  1926.  
  1927.    SYNOPSIS
  1928.     #include <sys/types.h>
  1929.     #include <sys/socket.h>
  1930.     #include <netinet/in.h>
  1931.  
  1932.     rslt = inet_aton (string, addr)
  1933.     D0          A0      A1
  1934.  
  1935.     int inet_aton (char *, struct in_addr *);
  1936.  
  1937.    FUNCTION
  1938.     Check whether "string" is a valid ASCII representation of an
  1939.     Internet address, and if so, convert to a binary address and
  1940.     store that in "addr".
  1941.  
  1942.    INPUTS
  1943.     string        address string. "123.45.67.89" for example
  1944.  
  1945.    RESULT
  1946.     1 if the address if valid, 0 if not.
  1947.  
  1948.    EXAMPLE
  1949.  
  1950.    NOTES
  1951.     This should replace inet_addr(), the return value of which
  1952.     cannot distinguish between failure and a local broadcast
  1953.     address.
  1954.  
  1955.     I-Net 225 ONLY.
  1956.  
  1957.     Not available in Surfer.
  1958.  
  1959.    BUGS
  1960.  
  1961.    SEE ALSO
  1962.  
  1963. socket.library/inet_lnaof                           socket.library/inet_lnaof
  1964.  
  1965.    NAME
  1966.     inet_lnaof -- give the local network address
  1967.  
  1968.    SYNOPSIS
  1969.     #include <sys/types.h>
  1970.     #include <sys/socket.h>
  1971.     #include <netinet/in.h>
  1972.  
  1973.     addr = inet_lnaof( in )
  1974.     D0           D1
  1975.  
  1976.     int inet_lnaof ( struct in_addr );
  1977.  
  1978.    FUNCTION
  1979.     Returns the local network address.
  1980.  
  1981.    INPUTS
  1982.     in        - struct in_addr to find local network part of.
  1983.  
  1984.     struct in_addr {
  1985.         u_long s_addr; /* a long containing the internet address */
  1986.     };
  1987.  
  1988.    RESULT
  1989.     addr        -  the local network address portion of 'in.'
  1990.  
  1991.    EXAMPLE
  1992.  
  1993.    NOTES
  1994.     'in' is *NOT* a pointer to a struct in_addr, it IS a structure.
  1995.     It is a 4-byte structure and is a passed as a structure (rather
  1996.     than a long or pointer to a structure) for historical reasons.
  1997.  
  1998.    RESULT
  1999.  
  2000.    EXAMPLE
  2001.  
  2002.    NOTES
  2003.  
  2004.    BUGS
  2005.  
  2006.    SEE ALSO
  2007.     inet_addr(), inet_makeaddr(), inet_netof()
  2008.  
  2009. socket.library/inet_makeaddr                     socket.library/inet_makeaddr
  2010.  
  2011.    NAME
  2012.     inet_makeaddr -- make internet address from network and host
  2013.  
  2014.    SYNOPSIS
  2015.     #include <sys/types.h>
  2016.     #include <sys/socket.h>
  2017.     #include <netinet/in.h>
  2018.  
  2019.     addr = inet_makeaddr (net, lna)
  2020.     D0              D0   D1
  2021.  
  2022.     struct in_addr inet_makeaddr (int, int);
  2023.  
  2024.    FUNCTION
  2025.     Formulate an Internet address from network + host.  Used in
  2026.     building addresses stored in the ifnet structure.
  2027.  
  2028.     'in' is *NOT* a pointer to a struct in_addr, it IS a structure.
  2029.     It is a 4-byte structure and is a passed as a structure (rather
  2030.     than a long or pointer to a structure) for historical reasons.
  2031.     See NOTES.
  2032.  
  2033.  
  2034.    INPUTS
  2035.     net        - network number in local integer format.
  2036.     lna        - local node address in local integer format.
  2037.  
  2038.    RESULT
  2039.     in        - struct in_addr.
  2040.  
  2041.     struct in_addr {
  2042.         u_long s_addr; /* a long containing the internet address */
  2043.     };
  2044.  
  2045.    EXAMPLE
  2046.  
  2047.    NOTES
  2048.     'in' is *NOT* a pointer to a struct in_addr, it IS a structure.
  2049.     It is a 4-byte structure and is a passed as a structure (rather
  2050.     than a long or pointer to a structure) for historical reasons.
  2051.  
  2052.    BUGS
  2053.  
  2054.    SEE ALSO
  2055.     inet_addr(), inet_lnaof(), inet_netof()
  2056.  
  2057. socket.library/inet_netof                           socket.library/inet_netof
  2058.  
  2059.    NAME
  2060.     inet_netof -- give the network number of an address
  2061.  
  2062.    SYNOPSIS
  2063.     #include <sys/types.h>
  2064.     #include <sys/socket.h>
  2065.     #include <netinet/in.h>
  2066.  
  2067.     net = inet_netof( in )
  2068.     D0          D1
  2069.  
  2070.     int inet_netof( struct in_addr );
  2071.  
  2072.    FUNCTION
  2073.     Returns the network number.
  2074.  
  2075.    INPUTS
  2076.     in        - struct in_addr to find network part of.
  2077.  
  2078.     struct in_addr {
  2079.         u_long s_addr; /* a long containing the internet address */
  2080.     };
  2081.  
  2082.    RESULT
  2083.     net        - network part of 'in.'
  2084.    EXAMPLE
  2085.  
  2086.    NOTES
  2087.     'in' is *NOT* a pointer to a struct in_addr, it IS a structure.
  2088.     It is a 4-byte structure and is a passed as a structure (rather
  2089.     than a long or pointer to a structure) for historical reasons.
  2090.  
  2091.    BUGS
  2092.  
  2093.    SEE ALSO
  2094.     inet_addr(), inet_makeaddr(), inet_lnaof()
  2095.  
  2096. socket.library/inet_network                       socket.library/inet_network
  2097.  
  2098.    NAME
  2099.     inet_network -- make network number from string
  2100.  
  2101.    SYNOPSIS
  2102.     #include <sys/types.h>
  2103.     #include <sys/socket.h>
  2104.     #include <netinet/in.h>
  2105.  
  2106.     net = inet_network( string )
  2107.     D0            A1
  2108.  
  2109.     int inet_network( char * );
  2110.  
  2111.    FUNCTION
  2112.     Converts a string to an network number if the string contains the
  2113.     dotted-decimal representation of a network number. All network
  2114.     numbers are in network order.
  2115.  
  2116.    INPUTS
  2117.     string        - network string. "123.45.67.89" for example.
  2118.  
  2119.    RESULT
  2120.     net        - INADDR_NONE is returned if input is invalid, else
  2121.               the network number corresponding to 'string.'
  2122.  
  2123.    EXAMPLE
  2124.  
  2125.    NOTES
  2126.  
  2127.    BUGS
  2128.  
  2129.    SEE ALSO
  2130.  
  2131. socket.library/inet_ntoa                             socket.library/inet_ntoa
  2132.  
  2133.    NAME
  2134.     inet_ntoa -- turn internet address into string
  2135.  
  2136.    SYNOPSIS
  2137.     #include <sys/types.h>
  2138.     #include <sys/socket.h>
  2139.     #include <netinet/in.h>
  2140.  
  2141.     string = inet_ntoa( in )
  2142.     D0            D1
  2143.  
  2144.     char *inet_ntoa ( struct in_addr );
  2145.  
  2146.    FUNCTION
  2147.     Converts an internet address to an ASCII string in the format
  2148.     "a.b.c.d" (dotted-decimal notation).
  2149.  
  2150.    INPUTS
  2151.     in        - struct in_addr.
  2152.  
  2153.     struct in_addr {
  2154.         u_long s_addr; /* a long containing the internet address */
  2155.     };
  2156.  
  2157.    RESULT
  2158.     Pointer to a string containing the ASCII ethernet address.
  2159.     For example, if in.s_addr = 0xc009d203 then a pointer
  2160.     to the string "192.9.210.3" is returned.
  2161.  
  2162.    NOTES
  2163.     The result points to a static buffer that is overwritten
  2164.     with each call.
  2165.  
  2166.     'in' is *NOT* a pointer to a struct in_addr, it IS a structure.
  2167.     It is a 4-byte structure and is a passed as a structure (rather
  2168.     than a long or pointer to a structure) for historical reasons.
  2169.  
  2170.    BUGS
  2171.  
  2172.    SEE ALSO
  2173.  
  2174. socket.library/listen                                   socket.library/listen
  2175.  
  2176.    NAME
  2177.     listen -- Indicate willingness to accept() connections.
  2178.  
  2179.    SYNOPSIS
  2180.     return = listen (s, backlog)
  2181.     D0         D0 D1
  2182.  
  2183.     int listen (int, int);
  2184.  
  2185.    FUNCTION
  2186.     This function is used for a connection-oriented server (i.e. one
  2187.     using the TCP protocol) to indicate that it is waiting to receive
  2188.     connections.  It is usually executed after socket() and bind(), and
  2189.     before accept().
  2190.  
  2191.    INPUTS
  2192.     s        - socket descriptor.
  2193.     backlog     - max number of connection requests to queue
  2194.               (usually 5).
  2195.  
  2196.    RESULT
  2197.     return        - 0 is returned if successful, else  -1. On error,
  2198.               errno will be set to one of the following:
  2199.  
  2200.     EBADF        - s is not a valid descriptor
  2201.     ENOTSOCK    - s is not a socket
  2202.     ECONNREFUSED    - connection refused, normally because the queue
  2203.               is full
  2204.     EOPNOTSUPP    - s is a socket type which does not support this
  2205.               operation.  s must be type SOCK_STREAM.
  2206.  
  2207.    BUGS
  2208.     'backlog' is currently limited to 5, although this
  2209.     is completely arbitrary.
  2210.  
  2211.    SEE ALSO
  2212.     accept(), bind(), connect(), socket()
  2213.  
  2214. socket.library/rcmd                                       socket.library/rcmd
  2215.  
  2216.    NAME
  2217.     rcmd - Allow superuser to execute commands on remote machines
  2218.  
  2219.    SYNOPSIS
  2220.     rem = rcmd( ahost, inport, luser, ruser, cmd, fd2p )
  2221.     D0        D0       D1       A0      A1     A2   D2
  2222.  
  2223.     int rcmd( char **, u_short, char *, char *, char *, int *);
  2224.  
  2225.    FUNCTION
  2226.     This function is used by rsh and rcp to communicate with rshd.
  2227.  
  2228.     The rcmd subroutine looks up the host *ahost using gethostbyname,
  2229.     returning (-1) if the host does not exist. Otherwise *ahost is
  2230.     set to the standard name of the host and a connection is
  2231.     established to a server residing at the well-known Internet port
  2232.     inport.
  2233.  
  2234.     If the call succeeds, a socket of type SOCK_STREAM is returned to
  2235.     the caller and given to the remote command as stdin and stdout.
  2236.     If fd2p is nonzero, then an auxiliary channel to a control
  2237.     process will be set up, and a descriptor for it will be placed in
  2238.     *fd2p. The control process will return diagnostic output from the
  2239.     command (unit 2) on this channel, and will also accept bytes on
  2240.     this channel as being UNIX signal numbers, to be forwarded to the
  2241.     process group of the command. If fd2p is 0, then the stderr (unit
  2242.     2 of the remote command) will be made the same as the stdout and
  2243.     no provision is made for sending arbitrary signals to the remote
  2244.     process, although you may be able to get its attention by using
  2245.     out-of-band data.
  2246.  
  2247.    INPUTS
  2248.     ahost        - pointer to a pointer to a host name.
  2249.     inport        - an Internet port.
  2250.     luser        - the local user's name.
  2251.     ruser        - the remote user's name.
  2252.     cmd        - the command string to be executed.
  2253.     fd2p        - a flag telling whether to use an auxillary channel.
  2254.  
  2255.    RESULT
  2256.     rem        - socket of type SOCK_STREAM if successful, else -1.
  2257.  
  2258.  
  2259. socket.library/reconfig                               socket.library/reconfig
  2260.  
  2261.    NAME
  2262.     reconfig - re-initialize the internal configuration structure
  2263.  
  2264.    SYNOPSIS
  2265.     return = reconfig ()
  2266.     D0
  2267.  
  2268.     BOOL reconfig (void);
  2269.  
  2270.    FUNCTION
  2271.     Causes the socket library to read the INet:s/inet.config file.
  2272.     This is useful for when you have changed an entry in the file
  2273.     and need the system to recognize the change without a system
  2274.     reboot.
  2275.  
  2276.    INPUTS
  2277.     None
  2278.  
  2279.    RESULT
  2280.     Boolean return - TRUE upon success, FALSE upon error
  2281.  
  2282.    NOTES
  2283.     Make -no- assumptions about how this works internally.
  2284.  
  2285.     It is generally safe to change any of the values in inet.config, but
  2286.     be aware that while some will take immediate effect (e.g., usedns),
  2287.     others may not have any effect until after a network restart (e.g.,
  2288.     changing syslogconsole after the SYSLOG window is already visible).
  2289.  
  2290.     Also, programs that have stored values based on the contents of
  2291.     inet.config will likely not re-read that information until they are
  2292.     restarted.
  2293.  
  2294.    BUGS
  2295.  
  2296.    SEE ALSO
  2297.  
  2298. socket.library/recv                                       socket.library/recv
  2299.  
  2300.    NAME
  2301.     recv, recvfrom, recvmsg -- Receive a message from a socket.
  2302.  
  2303.    SYNOPSIS
  2304.     #include <sys/types.h>
  2305.     #include <sys/socket.h>
  2306.  
  2307.     numbytes = recv (s, buf, len, flags)
  2308.     D0         D0 A0     D1   D2
  2309.  
  2310.     numbytes = recvfrom (s, buf, len, flags, from, fromlen)
  2311.     D0             D0 A0    D1  D2     A1    A2
  2312.  
  2313.     numbytes = recvmsg (s, msg, flags)
  2314.     D0            D0 A0   D1
  2315.  
  2316.     int recv (int, char *, int, int)
  2317.     int recvfrom (int, char *, int, int, struct sockaddr *, int *)
  2318.     int recvmsg (int, struct msghdr *, int)
  2319.  
  2320.    FUNCTION
  2321.     recv() is used to receive messages on an already connect()'ed
  2322.     socket.
  2323.  
  2324.     recvfrom() receives data from a socket whether it is in a connected
  2325.     state or not.
  2326.  
  2327.     recvmsg() is the most general of the recv calls and is for advanced
  2328.     use.
  2329.  
  2330.     If no data is available, these calls block unless the socket is
  2331.     set to nonblocking in which case (-1) is returned with errno set
  2332.     to EWOULDBLOCK.
  2333.  
  2334.    INPUTS
  2335.     s        - a socket descriptor.
  2336.     buf        - the buffer into which the incoming data will be
  2337.               placed.
  2338.     len        - the size of the buffer.
  2339.     flags        - select options (MSG_OOB, MSG_PEEK).
  2340.     from        - a pointer to a sockaddr structure.
  2341.     fromlen     - Length of the 'from' buffer.
  2342.     msg        - pointer to a struct msghdr, defined in
  2343.               "sys/socket.h."
  2344.  
  2345.    RESULT
  2346.     numbytes    - number of bytes read if successful else -1.
  2347.  
  2348.    NOTES
  2349.     'fromlen' is passed with the length of the 'from' buffer.  If 'from'
  2350.     is non-zero, the structure will be filled with the source address
  2351.     and fromlen will be filled in to represent the size of the actual
  2352.     address stored in 'from'.
  2353.  
  2354.    SEE ALSO
  2355.     send(), socket(), connect(), bind(), listen(), accept()
  2356.  
  2357. socket.library/select                                   socket.library/select
  2358.  
  2359.    NAME
  2360.     select -- Examines specified sockets' read, write or exception status.
  2361.  
  2362.    SYNOPSIS
  2363.     num = select( numfds, readfds, writefds, exceptfds, timeout )
  2364.     D0          D0      A0       A1     A2        D1
  2365.  
  2366.     int select( int, fd_set *, fd_set *, fd_set *, struct timeval *);
  2367.  
  2368.    FUNCTION
  2369.     select() examines the socket masks specified 'readfds,' 'writefds,'
  2370.     and 'execptfds' (see FD_SET) to see if they are ready for reading,
  2371.     for writing, or have an exceptional condition pending.
  2372.  
  2373.     When select() returns, the masks will have been modified so that
  2374.     only the "bits" for those sockets on which an event has occured are
  2375.     set.  The total number of ready sockets is returned in 'num.'
  2376.  
  2377.     If 'timeout' is a non-NULL pointer, it specifies a maximum
  2378.     interval to wait for the selection to complete. If timeout is
  2379.     a NULL pointer, the select blocks indefinitely. To affect a
  2380.     poll, the timeout argument should be nonzero, pointing to a
  2381.     zero valued timeval structure.    As you know, busy-loop polling
  2382.     is a no-no on the Amiga.
  2383.  
  2384.     Any of readfds, writefds, and execptfds may be given as NULL if
  2385.     any of those categories are not of interest.
  2386.  
  2387.     select() should not be used with a single socket (use s_getsignal()
  2388.     and Wait() instead).
  2389.  
  2390.    INPUTS
  2391.     numfds      - Maximum number of bits in the masks that
  2392.             represent valid file descriptors.
  2393.     readfds   - 32 bit mask representing read file descriptors
  2394.     writefds  - 32 bit mask representing write file descriptors
  2395.     exceptfds - 32 bit mask representing except file descriptors
  2396.     timeout   - Pointer to a timeval structure which holds the
  2397.             maximum amount of time to wait for the selection
  2398.             to complete.
  2399.  
  2400.    RESULT
  2401.     num      - The number of ready sockets, zero if a timeout occurred,
  2402.             -1 on error.
  2403.     readfds   - A mask of the ready socket descriptors
  2404.     writefds  -     "      "     "     "      "
  2405.     exceptfds -     "      "     "     "      "
  2406.  
  2407.    NOTES
  2408.     If a process is blocked on a select() waiting for input from a
  2409.     socket and the sending process closes the socket, the select
  2410.     notes this as an exception rather than as data.  Hence, if
  2411.     the select is not currently looking for exceptions, it will
  2412.     wait forever.
  2413.  
  2414.     The descriptor masks are always modified on return, even if
  2415.     the call returns as the result of the timeout.
  2416.  
  2417.     The current version of this function calls selectwait()
  2418.     with a control-C option in the umask field.
  2419.  
  2420.     A common error is to use the socket number in which you are
  2421.     interested as the first argument. Use socket+1.
  2422.  
  2423.    BUGS
  2424.  
  2425.    SEE ALSO
  2426.     FD_SET(), selectwait(), s_getsignal()
  2427.  
  2428. socket.library/selectwait                           socket.library/selectwait
  2429.  
  2430.    NAME
  2431.     selectwait -- select() with optional, task specific Wait() mask.
  2432.  
  2433.    SYNOPSIS
  2434.     num = selectwait( numfds, rfds, wfds, exfds, time, umask )
  2435.     D0          D0      A0    A1    A2     D1    D2
  2436.  
  2437.     int selectwait (int, int *, int *, int *, struct timeval *, long *);
  2438.  
  2439.    FUNCTION
  2440.     selectwait() is the same as select() except that it processes
  2441.     one additional argument, 'umask'
  2442.  
  2443.     The umask argument should contain either a NULL or a mask
  2444.     of the desired task-specific signal bits that will be tested
  2445.     along with the socket descriptors.  selectwait() does a standard
  2446.     Exec Wait() call and adds the supplied mask value to Wait()
  2447.     argument.
  2448.  
  2449.    INPUTS
  2450.     numfds      - The maximum number of bits in the masks that
  2451.             represent valid file descriptors.
  2452.     readfds   - 32 bit mask representing read file descriptors
  2453.     writefds  - 32 bit mask representing write file descriptors
  2454.     exceptfds - 32 bit mask representing except file descriptors
  2455.     timeout   - A pointer to a timeval structure which holds the
  2456.             maximum amount of time to wait for the selection
  2457.             to complete.
  2458.     umask      - A mask of the task's signal bits that will be
  2459.             used (in addition to the standard select() call
  2460.             return options) to have the call return. This can
  2461.             be SIGBREAKF signals, Intuition userport signals,
  2462.             console port signals, etc. Any mask that you would
  2463.             pass to the the Exec Wait() call is ok here.
  2464.  
  2465.    RESULT
  2466.     num      - The number of ready file descriptors if
  2467.             successful.  Zero (0) if a timeout occurred.
  2468.             (-1) upon error.
  2469.     readfds   - A mask of the ready file descriptors
  2470.     writefds  -     "      "     "     "      "
  2471.     exceptfds -     "      "     "     "      "
  2472.     umask      - A mask of the bits in the originally passed 'umask'
  2473.             variable that have actually occured.
  2474.  
  2475.    EXAMPLE
  2476.     long umask = SIGBREAKF_CTRL_D | 1L << myport->mp_SigBit ;
  2477.  
  2478.     numfds = selectwait(n, r, w, e, time, &umask) ;
  2479.     if( event & SIGBREAKF_CTRL_D ) {
  2480.         printf("user hit CTRL-D\n") ;
  2481.     }
  2482.     if( event & 1L << myport->mp_SigBit ) {
  2483.         printf( "myport got a message\n" ) ;
  2484.     }
  2485.    NOTES
  2486.     A common error is to use the socket number in which you are
  2487.     interested as the first argument. Use socket+1.
  2488.  
  2489.    BUGS
  2490.  
  2491.    SEE ALSO
  2492.     FD_SET(), select(), s_getsignal()
  2493.  
  2494. socket.library/send                                       socket.library/send
  2495.  
  2496.    NAME
  2497.     send, sendto, sendmsg -- Send data from a socket.
  2498.  
  2499.    SYNOPSIS
  2500.     #include <sys/types.h>
  2501.     #include <sys/socket.h>
  2502.  
  2503.     cc = send (s, buf, len, flags)
  2504.     D0       D0 A0   D1    A1
  2505.  
  2506.     cc = sendto (s, buf, len, flags, to, to_len)
  2507.     D0         D0 A0   D1   D2     A1  D3
  2508.  
  2509.     cc = sendmsg (s, msg, flags)
  2510.     D0          D0 A0   D1
  2511.  
  2512.     int send (int, char *, int, int);
  2513.     int sendto (int, char *, int, int, struct sockaddr *, int);
  2514.     int sendmsg (int, struct msghdr *, int);
  2515.  
  2516.    FUNCTION
  2517.     send(), sendto(), and sendmsg() transmit data from a socket.
  2518.     send() must be used with a connect()'ed socket.  sendto() can
  2519.     only be used with non-connect()'ed DGRAM-type sockets.  sendmsg()
  2520.     is an advanced function.
  2521.  
  2522.    INPUTS
  2523.     s        - socket descriptor.
  2524.     buf        - pointer to message buffer.
  2525.     len        - length of message to transmit.
  2526.     flags        - 0 or MSG_OOB to send out-of-band data.
  2527.     to        - pointer to a sockaddr containing the destination.
  2528.     to_len        - sizeof(struct sockaddr).
  2529.     msg        - pointer to a struct msghdr, defined in
  2530.               "sys/socket.h."
  2531.  
  2532.    RESULT
  2533.     cc        - the number of bytes sent. This does not imply that
  2534.               the bytes were recieved.  -1 is returned on a local
  2535.               error (errno will be set to the specific error
  2536.               code).  Possible errors are:
  2537.  
  2538.         EBADF        an invalid descriptor was used
  2539.         ENOTSOCK    's' is not a socket
  2540.         EMSGSIZE    the socket requires that the message be
  2541.                 sent atomically and the size of the message
  2542.                 prevents that.
  2543.         EWOULDBLOCK    requested operation would block
  2544.  
  2545.    EXAMPLE
  2546.  
  2547.    NOTES
  2548.  
  2549.    BUGS
  2550.  
  2551.    SEE ALSO
  2552.     recv(), socket()
  2553.  
  2554. socket.library/setgid                                   socket.library/setgid
  2555.  
  2556.    NAME
  2557.     setgid    -- Set group id.
  2558.  
  2559.    SYNOPSIS
  2560.     #include <sys/types.h>
  2561.  
  2562.     return = setgid (gid)
  2563.     D0         D0
  2564.  
  2565.     int setgid (gid_t);
  2566.  
  2567.    FUNCTION
  2568.     Sets the group id to the specified gid.
  2569.  
  2570.    INPUTS
  2571.     The gid to set the group id to.
  2572.  
  2573.    RESULT
  2574.     return        - zero or -1 (on error).
  2575.  
  2576.               The socket.library configuration information for the
  2577.               group id will be updated.
  2578.    EXAMPLE
  2579.  
  2580.    NOTES
  2581.     This is an emulation of the Unix setgid() function. The Unix
  2582.     setegid() is equivalent to setgid() on the Amiga.
  2583.  
  2584.     Currently, configuration information is stored in memory in a
  2585.     configuration structure.  This structure is initialized when
  2586.     the network functions are started, and the data comes from
  2587.     "INet:s/inet.config". There is no support for multiple user
  2588.     IDs on a single Amiga because the Amiga OS has no concept of
  2589.     multiple users.
  2590.  
  2591.     I-Net 225 ONLY.
  2592.  
  2593.    BUGS
  2594.  
  2595.    SEE ALSO
  2596.     setuid()
  2597.  
  2598. socket.library/setgrent                               socket.library/setgrent
  2599.  
  2600.    NAME
  2601.     setgrent - Opens or rewinds the group file.
  2602.  
  2603.    SYNOPSIS
  2604.     setgrent (flag)
  2605.           D1
  2606.  
  2607.     void setgrent (int);
  2608.  
  2609.    FUNCTION
  2610.     If the file is already open the file is rewound. Otherwise the
  2611.     file is opened.
  2612.  
  2613.    INPUTS
  2614.     flag        - if 'flag' is 1, calls to getgrgid() and getgrnam()
  2615.               will not close the file between calls.  You must
  2616.               close the file with an endgrent().  Once set,
  2617.               'flag' cannot be reset except by calling endgrent().
  2618.  
  2619.    RESULT
  2620.     None.
  2621.  
  2622.    NOTES
  2623.  
  2624.     I-Net 225 ONLY.
  2625.  
  2626.    SEE ALSO
  2627.     endgrent(), getgrent()
  2628.  
  2629. socket.library/sethostent                           socket.library/sethostent
  2630.  
  2631.    NAME
  2632.     sethostent -- Rewind the hosts file ("INet:db/hosts").
  2633.  
  2634.    SYNOPSIS
  2635.     sethostent (flag)
  2636.  
  2637.     void sethostent (int);
  2638.              D1
  2639.  
  2640.    FUNCTION
  2641.     This function is rarely useful.
  2642.  
  2643.     Opens the host file if necessary.  Rewinds the host file if it
  2644.     is open.
  2645.  
  2646.    INPUTS
  2647.     flag        - If 'flag' is 1, calls to gethostbyname() and
  2648.               gethostbyaddr() will not close the file between
  2649.               calls.  You must close the file with an
  2650.               endhostent().  Once set, 'flag' cannot be reset
  2651.               except by calling endhostent().
  2652.  
  2653.    RESULT
  2654.     None.
  2655.  
  2656.    EXAMPLE
  2657.  
  2658.    NOTES
  2659.  
  2660.    BUGS
  2661.  
  2662.    SEE ALSO
  2663.     gethostent(), gethostbyname(), gethostbyaddr(), endhostent()
  2664.  
  2665. socket.library/setnetent                             socket.library/setnetent
  2666.  
  2667.    NAME
  2668.     setnetent -- Open or rewind the networks file.
  2669.  
  2670.    SYNOPSIS
  2671.     setnetent (flag)
  2672.            D1
  2673.  
  2674.     void setnetent (int);
  2675.  
  2676.    FUNCTION
  2677.     Rewinds the network file if it is open.
  2678.     Opens the network file if it was not open.
  2679.  
  2680.    INPUTS
  2681.     flag        - if 'flag' is 1, calls to getnetbyname() and
  2682.               getnetbyaddr() will not close the file between
  2683.               calls.  You must close the file with an endnetent().
  2684.               Once set, 'flag' cannot be reset except by calling
  2685.               endnetent().
  2686.  
  2687.    RESULT
  2688.     None.
  2689.  
  2690.    EXAMPLE
  2691.  
  2692.    NOTES
  2693.  
  2694.    BUGS
  2695.  
  2696.    SEE ALSO
  2697.     getnetent(), getnetbyname(), getnetbyaddr(), endnetent()
  2698.  
  2699. socket.library/setprotoent                         socket.library/setprotoent
  2700.  
  2701.    NAME
  2702.     setprotoent -- Open or rewind the protocols file.
  2703.  
  2704.    SYNOPSIS
  2705.     setprotoent (flag)
  2706.  
  2707.     void setprotoent (int);
  2708.               D1
  2709.  
  2710.    FUNCTION
  2711.     This function is rarely useful.
  2712.  
  2713.     Opens the protocols file if necessary.
  2714.     Rewinds the protocols file if it is open.
  2715.  
  2716.    INPUTS
  2717.     flag        - if 'flag' is 1, calls to getprotobyname() and
  2718.               getprotobynumber() will not close the file
  2719.               between calls.  You must close the file with an
  2720.               endprotoent().  Once set, 'flag' cannot be reset
  2721.               except by calling endprotoent().
  2722.    RESULT
  2723.     None.
  2724.  
  2725.    EXAMPLE
  2726.  
  2727.    NOTES
  2728.  
  2729.    BUGS
  2730.  
  2731.    SEE ALSO
  2732.     getprotoent(), endprotoent(), getprotobyname(), getprotobynumber()
  2733.  
  2734. socket.library/setpwent                               socket.library/setpwent
  2735.  
  2736.    NAME
  2737.     setpwent - Opens or rewinds the password file.
  2738.  
  2739.    SYNOPSIS
  2740.     setpwent (flag)
  2741.           D1
  2742.  
  2743.     void setpwent (int);
  2744.  
  2745.    FUNCTION
  2746.     If the password file is already open, it is reset to the beginning.
  2747.     Otherwise, it is opened.
  2748.  
  2749.    INPUTS
  2750.     flag        - if 'flag' is 1, calls to getpwuid() and getpwnam()
  2751.               will not close the file between calls.  You must
  2752.               close the file with an endpwent().  Once set,
  2753.               'flag' cannot be reset except by calling endpwent().
  2754.  
  2755.    RESULT
  2756.     None.
  2757.  
  2758.    SEE ALSO
  2759.     endpwent(), getpwent()
  2760.  
  2761. socket.library/setservent                           socket.library/setservent
  2762.  
  2763.    NAME
  2764.     setservent -- Open or rewind the services file.
  2765.  
  2766.    SYNOPSIS
  2767.     setservent (flag)
  2768.             D1
  2769.  
  2770.     void setservent (int);
  2771.  
  2772.    FUNCTION
  2773.     This function is rarely useful.
  2774.  
  2775.     Opens the services file if necessary.
  2776.     Rewinds the services file if it is open.
  2777.  
  2778.    INPUTS
  2779.     flag        - if 'flag' is 1, calls to getservbyport() and
  2780.               getservbyname() will not close the file between
  2781.               calls.  You must close the file with an
  2782.               endservent().  Once set, 'flag' cannot be reset
  2783.               except by calling endservent().
  2784.  
  2785.    EXAMPLE
  2786.  
  2787.    NOTES
  2788.  
  2789.    BUGS
  2790.  
  2791.    SEE ALSO
  2792.     getservent(), endservent()
  2793.  
  2794. socket.library/setsockopt                           socket.library/setsockopt
  2795.  
  2796.    NAME
  2797.     setsockopt -- Set socket options.
  2798.  
  2799.    SYNOPSIS
  2800.     return = setsockopt (s, level, optname, optval, optlen)
  2801.     D0             D0 D1     D2    A0    D3
  2802.  
  2803.     int setsockopt (int, int, int, char *, int);
  2804.  
  2805.    FUNCTION
  2806.     Sets the option specified by 'optname' for socket 's.'
  2807.     This is an advanced function.  See the "sys/socket.h" header and
  2808.     your favorite TCP/IP reference for more information on options.
  2809.  
  2810.    INPUTS
  2811.     s        - socket descriptor.
  2812.     level        - protocol level.  Valid levels are:
  2813.                IPPROTO_IP    IP options
  2814.                IPPROTO_TCP    TCP options
  2815.                SOL_SOCKET    socket options
  2816.     optname     - option name.
  2817.     optval        - pointer to the buffer with the new value.
  2818.     optlen        - size of 'optval' (in bytes).
  2819.  
  2820.    RESULT
  2821.     return        - 0 if successful else -1 (errno will contain the
  2822.               specific error).
  2823.  
  2824.    EXAMPLE
  2825.         int on = 1;
  2826.         setsockopt( s, SOL_SOCKET, SO_DEBUG, &on, (int) sizeof (on));
  2827.  
  2828.    NOTES
  2829.  
  2830.    BUGS
  2831.  
  2832.    SEE ALSO
  2833.     getsockopt()
  2834.  
  2835. socket.library/setuid                                   socket.library/setuid
  2836.  
  2837.    NAME
  2838.     setuid    -- Set user id.
  2839.  
  2840.    SYNOPSIS
  2841.     #include <sys/types.h>
  2842.  
  2843.     return = setuid (uid)
  2844.     D0         D0
  2845.  
  2846.     int setuid (uid_t);
  2847.  
  2848.    FUNCTION
  2849.     Sets the user id to the specified uid, if the uid is valid.
  2850.  
  2851.    INPUTS
  2852.     The uid to set the user id to.
  2853.  
  2854.    RESULT
  2855.     return        - zero or -1 (on error). The uid must be present
  2856.               in INet:db/passwd for the call to be valid.
  2857.  
  2858.               The socket.library configuration information for the
  2859.               uid and the username will be updated.
  2860.    EXAMPLE
  2861.  
  2862.    NOTES
  2863.     This is an emulation of the Unix setuid() function. The Unix
  2864.     seteuid() is equivalent to setuid() on the Amiga.
  2865.  
  2866.     Currently, configuration information is stored in memory in a
  2867.     configuration structure.  This structure is initialized when
  2868.     the network functions are started, and the data comes from
  2869.     "INet:s/inet.config". There is no support for multiple user
  2870.     IDs on a single Amiga because the Amiga OS has no concept of
  2871.     multiple users.
  2872.  
  2873.     I-Net 225 ONLY.
  2874.  
  2875.    BUGS
  2876.  
  2877.    SEE ALSO
  2878.     setgid()
  2879.  
  2880. socket.library/setup_sockets                     socket.library/setup_sockets
  2881.  
  2882.    NAME
  2883.     setup_sockets -- Initialize global data for sockets.
  2884.  
  2885.    SYNOPSIS
  2886.     retval = setup_sockets (max_sockets, errnop);
  2887.     D0            D1         A0
  2888.  
  2889.     ULONG setup_sockets (UWORD, int *);
  2890.  
  2891.    FUNCTION
  2892.     This function initializes the MAXSOCKS global variable, optionally
  2893.     sets the library error pointer to the application's errno, and
  2894.     allocates two signal bits (SIGIO and SIGURG).
  2895.  
  2896.     This should be called immediately after an OpenLibrary(). As of
  2897.     socket.library version 6.24, "errnop" may be NULL, and the
  2898.     library will use an internal error pointer safely.
  2899.  
  2900.     If 'max_sockets' is greater than FD_SETSIZE, or two signal bits
  2901.     cannot be allocated, setup_sockets() will return false. FD_SETSIZE
  2902.     is currently 128 (see <sys/types.h>).
  2903.  
  2904.     setup_sockets() should not be called more than once in a
  2905.     program, especially if there are already open sockets.
  2906.  
  2907.    INPUTS
  2908.     max_sockets    - maximum number of sockets that can be open at once.
  2909.     errno        - pointer to the global int 'errno.'
  2910.  
  2911.    RESULT
  2912.     retval        - TRUE on success, FALSE on failure.
  2913.  
  2914.    NOTES
  2915.     If you are using a language other than C, you must pass in a pointer
  2916.     to a variable that will hold the error numbers.
  2917.  
  2918.     In SAS C, errno is a global in c.o.  If you don't link with c.o
  2919.     you will have to declare errno locally.
  2920.  
  2921.     Allocation of 'socks' array was moved to library initialization code.
  2922.     Since the total array size only reaches 512 bytes (with FD_SETSIZE of
  2923.     128), its not big enough to worry about.  We simply allocate the max
  2924.     size, and just use the 'maxsocks' parameter for program specific
  2925.     range checks.
  2926.  
  2927.     The library's internal error pointer is not currently visible outside
  2928.     of the library. For any visibility to errors, the programmer should
  2929.     pass a pointer to a local variable.
  2930.  
  2931.    BUGS
  2932.  
  2933.    SEE ALSO
  2934.     cleanup_sockets()
  2935.  
  2936. socket.library/shutdown                               socket.library/shutdown
  2937.  
  2938.    NAME
  2939.     shutdown -- Shut down part of a full-duplex connection.
  2940.  
  2941.    SYNOPSIS
  2942.     return = shutdown (s, how)
  2943.     D0           D0 D1
  2944.  
  2945.     int shutdown (int, int);
  2946.  
  2947.    FUNCTION
  2948.     Sockets are normally terminated by using just s_close().  However,
  2949.     s_close() will attempt to deliver any data that is still pending.
  2950.     Further, shutdown() provides more control over how a connection is
  2951.     terminated.  You should eventually use s_close() on all sockets you
  2952.     own, regardless of what shutdown() is done on those sockets.
  2953.  
  2954.    INPUTS
  2955.     s        - socket descriptor.
  2956.     how        - 'how' can be one of the following:
  2957.               0    disallow further receives
  2958.               1    disallow further sends
  2959.               2    disallow further sends and receives
  2960.  
  2961.    RESULT
  2962.     return        - 0 if successful else -1 (errno will contain the
  2963.               specific error).
  2964.  
  2965.    EXAMPLE
  2966.  
  2967.    NOTES
  2968.  
  2969.    BUGS
  2970.  
  2971.    SEE ALSO
  2972.     s_close()
  2973.  
  2974. socket.library/socket                                   socket.library/socket
  2975.  
  2976.    NAME
  2977.     socket -- Create an endpoint for communication.
  2978.  
  2979.    SYNOPSIS
  2980.     s = socket (family, type, protocol)
  2981.     D0        D0        D1      D2
  2982.  
  2983.     int socket (int, int, int);
  2984.  
  2985.    FUNCTION
  2986.     socket() returns a socket descriptor for a socket with .
  2987.  
  2988.    INPUTS
  2989.     family     - This specifies an address format with which
  2990.            addresses specified in later operations using
  2991.            socket should be interpreted.
  2992.     type     - Specifies the semantics of communication.
  2993.     protocol - Specifies a particular protocol to be used with the
  2994.            socket.
  2995.  
  2996.    RESULT
  2997.     s     - Returns a (-1) upon failure ; a socket descriptor
  2998.            upon success.
  2999.  
  3000.    NOTES
  3001.     This function assumes a successful call to 'setup_sockets()'
  3002.     has already occured.
  3003.  
  3004.    SEE ALSO
  3005.  
  3006. socket.library/strerror                               socket.library/strerror
  3007.  
  3008.    NAME
  3009.     strerror - Returns a pointer to an error message.
  3010.  
  3011.    SYNOPSIS
  3012.     #include <string.h>
  3013.  
  3014.     error = strerror (error_number)
  3015.     D0          D1
  3016.  
  3017.     char *strerror (int);
  3018.  
  3019.    FUNCTION
  3020.     The strerror() function maps the error number to a error
  3021.     message.
  3022.  
  3023.    INPUTS
  3024.     error_number    - usually the value of errno.
  3025.  
  3026.    RESULT
  3027.     error        - pointer to the error message.
  3028.  
  3029.    NOTES
  3030.     This function should eventually be localized.
  3031.  
  3032.    SEE ALSO
  3033.     <errno.h>,  perror()
  3034.  
  3035. socket.library/syslog                                   socket.library/syslog
  3036.  
  3037.    NAME
  3038.     syslogA - log system messages
  3039.  
  3040.    SYNOPSIS
  3041.     error = syslogA (priority, message, argarray )
  3042.     D0         D0       A0        A1
  3043.  
  3044.     int syslogA (int, char *, int *);
  3045.  
  3046.     error = syslog (priority, message, ...)
  3047.  
  3048.     int syslog (int, char *, ...);
  3049.  
  3050.    FUNCTION
  3051.     syslog() writes the 'message' argument to a console window and/or
  3052.     a specified file. The priority field is used to determine which,
  3053.     if any, of the above options is used.  This function is compatible
  3054.     with the UNIX syslog() function, taking RawDoFmt()-style arguments.
  3055.     Basically, this is a wrapper for the above s_syslog() function,
  3056.     taking care of formatting the string before sending it.
  3057.  
  3058.     A newline is added to the end of the formatted string if not already
  3059.     present.
  3060.  
  3061.    NOTES
  3062.  
  3063.     I-Net 225 ONLY.
  3064.  
  3065.    BUGS
  3066.     none known
  3067.  
  3068.    SEE ALSO
  3069.     inet.config (in the I-Net 225 manual)
  3070.  
  3071. socket.library/s_close                                 socket.library/s_close
  3072.  
  3073.    NAME
  3074.     s_close -- Close a socket.
  3075.  
  3076.    SYNOPSIS
  3077.     status = s_close (socket);
  3078.     D0          D0
  3079.  
  3080.     int s_close (int);
  3081.  
  3082.    FUNCTION
  3083.     This function closes a socket.
  3084.  
  3085.    INPUTS
  3086.     unit    - socket number.
  3087.  
  3088.    RESULT
  3089.     status    - 0 if successful, else -1.
  3090.  
  3091.    EXAMPLE
  3092.  
  3093.    NOTES
  3094.     s_close() must always be used to close a socket.  This shared
  3095.     library does not know about filehandles or file descriptors.
  3096.  
  3097.    BUGS
  3098.  
  3099.    SEE ALSO
  3100.     socket()
  3101.  
  3102. socket.library/s_crypt                                 socket.library/s_crypt
  3103.  
  3104.    NAME
  3105.     s_crypt -- Password encryption
  3106.  
  3107.    SYNOPSIS
  3108.     rslt = s_crypt (buffer, password, username)
  3109.     D0        A0    A1      A2
  3110.  
  3111.     STRPTR s_crypt (STRPTR, STRPTR, STRPTR);
  3112.  
  3113.    FUNCTION
  3114.     This function takes a buffer of 32 characters in length, an
  3115.     unencrypted password and the user's name (as known to the host
  3116.     system) and returns an encrypted password in the passed buffer.
  3117.     This is a one-way encryption.  Normally, the user's encrypted
  3118.     password is stored in a file for future password comparison.
  3119.  
  3120.    INPUTS
  3121.     buffer       - a pointer to a buffer 32 bytes in length.
  3122.     password   - a pointer to an unencrypted password string.
  3123.     username   - a pointer to the user's name.
  3124.  
  3125.    RESULT
  3126.     A pointer to buffer on success, NULL on failure.
  3127.  
  3128.    EXAMPLE
  3129.  
  3130.    NOTES
  3131.     If a library file of 'Inet:libs/password.library' exists, the
  3132.     'make_password()' entry point of that library will be called to
  3133.     generate the encrypted password.  Otherwise, the old, standard
  3134.     password routine compatible with that used by the AS225 package
  3135.     will be called instead, for backwards compatibility.
  3136.  
  3137.     I-Net 225 ONLY.
  3138.  
  3139.     Not available in Surfer.
  3140.  
  3141.    BUGS
  3142.  
  3143.    SEE ALSO
  3144.     password.library/make_password
  3145.  
  3146. socket.library/s_dev_func                           socket.library/s_dev_func
  3147.  
  3148.    NAME
  3149.     s_dev_func -- set device function
  3150.  
  3151.    SYNOPSIS
  3152.     s_dev_func (u_long (*function)(int));
  3153.             A0               D0
  3154.  
  3155.     void s_dev_func (u_long (*function) (int))
  3156.  
  3157.    FUNCTION
  3158.     This function is intended to assist in the building of Unix
  3159.     compatibility libraries.  The function callback that is specified
  3160.     when calling s_dev_func() will be utilized to determine valid
  3161.     numbers that can be assigned as sockets (to avoid collision with
  3162.     file descriptors in user programs).
  3163.  
  3164.     For SAS/C 6.x, the routine should be __chkufb(). For DICE 3.0,
  3165.     the routine should be __getfh().
  3166.  
  3167.     Before assigning a socket identifier, socket.library will call
  3168.     this routine with a potential socket number. If it returns a
  3169.     zero value, socket.library will assign the next socket opened
  3170.     that potential number.
  3171.  
  3172.  
  3173.    INPUTS
  3174.     function - pointer to a function as described above
  3175.  
  3176.    EXAMPLE
  3177.  
  3178.    NOTES
  3179.     This is a kludge to get around some of the problems caused because
  3180.     a socket is not a file descriptor or a filehandle. If you don't
  3181.     understand why this function is here, you probably don't need it.
  3182.  
  3183.     I-Net 225 ONLY.
  3184.  
  3185.  
  3186. socket.library/s_dev_list                           socket.library/s_dev_list
  3187.  
  3188.    NAME
  3189.     s_dev_list -- set device list
  3190.  
  3191.    SYNOPSIS
  3192.     s_dev_list (res, size);
  3193.             D0      D1
  3194.  
  3195.     void s_dev_list (u_long, int);
  3196.  
  3197.    FUNCTION
  3198.     This function is intended to assist in the building of
  3199.     Unix compatibility libraries.  s_dev_list() is passed a pointer
  3200.     to an array that can be used to tell the socket library
  3201.     which socket numbers should not be used.  The socket library
  3202.     will not create a socket number 'X' if reserved[X] is set.
  3203.     The socket library will never change the contents of the
  3204.     reserved array.
  3205.  
  3206.     This function is compatible with SAS/C 5.x and before. For current
  3207.     releases of SAS/C, and for DICE, you should use s_dev_func()
  3208.     instead.
  3209.  
  3210.    INPUTS
  3211.     res    - pointer to device table
  3212.     size    - size of each entry in the device table
  3213.  
  3214.    EXAMPLE
  3215.  
  3216.    NOTES
  3217.     This is a kludge to get around some of the problems caused because
  3218.     a socket is not a file descriptor or a filehandle.
  3219.     If you don't understand why this function is here, you probably
  3220.     don't need it.
  3221.  
  3222.  
  3223. socket.library/s_dup                                     socket.library/s_dup
  3224.  
  3225.    NAME
  3226.     s_dup -- duplicate a socket descriptor
  3227.  
  3228.    SYNOPSIS
  3229.     status = s_dup (oldfd);
  3230.     D0        D0
  3231.  
  3232.     int s_dup (int);
  3233.  
  3234.    FUNCTION
  3235.     This function creates a copy of the socket oldfd.
  3236.  
  3237.     s_dup() is used to create a copy of the socket oldfd. When
  3238.     successful, the sockets may then be used interchangeably to
  3239.     refer to the same stream.
  3240.  
  3241.     s_dup() will return the lowest available unused descriptor
  3242.     number.
  3243.  
  3244.    INPUTS
  3245.     oldfd    - socket descriptor to copy.
  3246.  
  3247.    RESULT
  3248.     status    - number of the new socket descriptor, if
  3249.           successful; -1 if not successful.
  3250.  
  3251.    EXAMPLE
  3252.  
  3253.    NOTES
  3254.     If oldfd is less than zero, greater than the maximum allowed
  3255.     socket (per setup_sockets()), or not currently open, EBADF
  3256.     will be returned in errno.
  3257.  
  3258.     If there are no more available socket descriptions, EMFILE
  3259.     will be returned in errno.
  3260.  
  3261.     I-Net 225 ONLY.
  3262.  
  3263.    BUGS
  3264.  
  3265.    SEE ALSO
  3266.     socket(), s_dup2()
  3267.  
  3268. socket.library/s_dup2                                   socket.library/s_dup2
  3269.  
  3270.    NAME
  3271.     s_dup2 -- duplicate a socket descriptor
  3272.  
  3273.    SYNOPSIS
  3274.     status = s_dup2 (oldfd, newfd);
  3275.     D0         D0    D1
  3276.  
  3277.     int s_dup2 (int, int);
  3278.  
  3279.    FUNCTION
  3280.     This function creates a copy of the socket oldfd, and assigns
  3281.     the descriptor number indicated by newfd.
  3282.  
  3283.     s_dup2() is used to create a copy of the socket oldfd. When
  3284.     successful, the sockets may then be used interchangeably to
  3285.     refer to the same stream.
  3286.  
  3287.    INPUTS
  3288.     oldfd    - socket descriptor to copy.
  3289.     newfd    - the new socket descriptor number.
  3290.  
  3291.    RESULT
  3292.     status    - number of the new socket descriptor, if
  3293.           successful; -1 if not successful.
  3294.  
  3295.    EXAMPLE
  3296.  
  3297.    NOTES
  3298.     If oldfd is less than zero, greater than the maximum allowed
  3299.     socket (per setup_sockets()), or not currently open, EBADF
  3300.     will be returned in errno.
  3301.  
  3302.     If newfd is less than zero or greater than the maximum allowed
  3303.     socket (per setup_sockets()) EBADF will be returned in errno.
  3304.  
  3305.     If newfd is open, it will be closed.
  3306.  
  3307.     I-Net 225 ONLY.
  3308.  
  3309.    BUGS
  3310.  
  3311.    SEE ALSO
  3312.     socket(), s_dup()
  3313.  
  3314. socket.library/s_errno                                 socket.library/s_errno
  3315.  
  3316.    NAME
  3317.     s_errno - return value of library error number
  3318.  
  3319.    SYNOPSIS
  3320.     retval = s_errno ();
  3321.     D0
  3322.  
  3323.     int s_errno (void);
  3324.  
  3325.    FUNCTION
  3326.     This function returns the current error value in the
  3327.     library; whether the pointer set up by setup_sockets()
  3328.     was external or internal.
  3329.  
  3330.    INPUTS
  3331.     None.
  3332.  
  3333.    RESULT
  3334.     None.
  3335.  
  3336.    NOTES
  3337.  
  3338.     I-Net 225 ONLY.
  3339.  
  3340.     Not available in Surfer.
  3341.  
  3342.    BUGS
  3343.  
  3344.    SEE ALSO
  3345.     setup_sockets()
  3346.  
  3347. socket.library/s_getsignal                         socket.library/s_getsignal
  3348.  
  3349.    NAME
  3350.     s_getsignal -- Get a network signal bit.
  3351.  
  3352.    SYNOPSIS
  3353.     signal = s_getsignal (type);
  3354.     D0              D1
  3355.  
  3356.     BYTE s_getsignal (UWORD);
  3357.  
  3358.    FUNCTION
  3359.     This function returns a socket signal.    The socket signal can be
  3360.     used to Wait() on an event for the shared socket library.  The
  3361.     following signal types are supported:
  3362.  
  3363.     SIGIO    This signal indicates a socket is ready for
  3364.         asynchronous I/O.  This signal will be sent only if
  3365.         the socket has been set to async by calling ioctl()
  3366.         with a command of FIOASYNC.
  3367.  
  3368.     SIGURG    This signal indicates the presence of urgent or
  3369.         out-of-band data on a TCP socket.
  3370.  
  3371.    INPUTS
  3372.     type    - SIGIO or SIGURG.
  3373.  
  3374.    RESULT
  3375.     signal    - signal bit (0..31) or -1 if 'type' was invalid.
  3376.  
  3377.    EXAMPLE
  3378.  
  3379.    NOTES
  3380.     The SIGIO signal will only be set for sockets on which FIOASYNC has
  3381.     been set (with s_ioctl or s_setsockopts.)
  3382.  
  3383.    BUGS
  3384.  
  3385.    SEE ALSO
  3386.     s_ioctl(), select(), selectwait()
  3387.  
  3388. socket.library/s_inherit                             socket.library/s_inherit
  3389.  
  3390.    NAME
  3391.     s_inherit -- inherit a socket
  3392.  
  3393.    SYNOPSIS
  3394.     s = s_inherit (sockptr);
  3395.     D0           D1
  3396.  
  3397.     int s_inherit (void *);
  3398.  
  3399.    FUNCTION
  3400.     This function along with s_release() provide a way to pass a
  3401.     socket from one process to another.  s_inherit() will attach
  3402.     a socket that has been released to your process. Use instead
  3403.     of socket() when another process hands you a socket.
  3404.  
  3405.    INPUTS
  3406.     sockptr - really a pointer to an internal socket structure
  3407.  
  3408.    RESULT
  3409.     s    - socket descriptor (-1 on failure)
  3410.  
  3411.    EXAMPLE
  3412.     void main (void)
  3413.     {
  3414.         int errno, s;
  3415.         long opts [OPT_COUNT];
  3416.         struct RDargs *rdargs;
  3417.  
  3418.         memset ((char *) opts, 0, sizeof (opts));
  3419.         rdargs = ReadArgs (TEMPLATE, opts, NULL);
  3420.  
  3421.         if ((SockBase = OpenLibrary ("inet:libs/socket.library", 1)) == NULL)
  3422.         {
  3423.         goto exit1;
  3424.         }
  3425.         setup_sockets (5, &errno);
  3426.  
  3427.         / * now get our socket * /
  3428.         s = s_inherit ((void *)*(long *) opts [OPT_SOCKPTR]);
  3429.  
  3430.    NOTES
  3431.     Use with caution.  Calling s_inherit() with an invalid sockptr
  3432.     will cause serious problems.
  3433.  
  3434.    BUGS
  3435.     Not safe if an invalid pointer is passed.
  3436.  
  3437.    SEE ALSO
  3438.     s_release()
  3439.  
  3440. socket.library/s_ioctl                                 socket.library/s_ioctl
  3441.  
  3442.    NAME
  3443.     s_ioctl -- Control socket options.
  3444.  
  3445.    SYNOPSIS
  3446.     return = s_ioctl (s, cmd, data)
  3447.     D0          D0 D1   A0
  3448.  
  3449.     int s_ioctl (int, int, char *);
  3450.  
  3451.    FUNCTION
  3452.     Manipulates device options for a socket.
  3453.  
  3454.    INPUTS
  3455.     s        - socket descriptor.
  3456.     cmd        - command.
  3457.     data        - data.
  3458.  
  3459.     The following commands are supported:
  3460.  
  3461.     command     description            data points to
  3462.     -------     -----------            --------------
  3463.     FIONBIO     set/clear nonblocking I/O    int
  3464.     FIOASYNC    set/clear async I/O        int
  3465.     FIONREAD    get number of bytes to read    int
  3466.     SIOCATMARK    at out-of-band mark?        int
  3467.     SIOCSPGRP    set process group        int
  3468.     SIOCGPGRP    get process group        int
  3469.     SIOCADDRT    add route            struct rtentry
  3470.     SIOCDELRT    delete route            struct rtentry
  3471.     SIOCGIFCONF    get ifnet list            struct ifconf
  3472.     SIOCGIFFLAGS    get ifnet flags         struct ifreq
  3473.     SIOCSIFFLAGS    set ifnet flags         struct ifreq
  3474.     SIOCGIFMETRIC    get IF metric            struct ifreq
  3475.     SIOCSIFMETRIC    set IF metric            struct ifreq
  3476.     SIOCGARP    get ARP entry            struct arpreq
  3477.     SIOCSARP    get ARP entry            struct arpreq
  3478.     SIOCDARP    delete ARP entry        struct arpreq
  3479.  
  3480.     For more information, see a Unix reference manual.
  3481.  
  3482.    RESULT
  3483.     return        - 0 on success, else -1 (errno will be set to the
  3484.               specific error code).
  3485.  
  3486.    EXAMPLE
  3487.     int one = 1;
  3488.     ioctl (s, FIOASYNC, (char *) &one);
  3489.  
  3490.    NOTES
  3491.     The standard Unix ioctl() function operates on both files and
  3492.     sockets.  Some compiler vendors may supply an ioctl() function.
  3493.     Because of this, and because this function works only with
  3494.     sockets, it has been renamed to s_ioctl().
  3495.  
  3496.    BUGS
  3497.  
  3498.    SEE ALSO
  3499.     setsockopts()
  3500.  
  3501. socket.library/s_release                             socket.library/s_release
  3502.  
  3503.    NAME
  3504.     s_release -- release a socket
  3505.  
  3506.    SYNOPSIS
  3507.     sockptr = s_release (s);
  3508.     D0             D1
  3509.  
  3510.     void *s_release (int);
  3511.  
  3512.    FUNCTION
  3513.     This function along with s_inherit() provide a way to pass a
  3514.     socket from one process to another.  s_release(s) will
  3515.     "detach" socket s from the current process.  Your process
  3516.     will no longer know about the socket.  You can not call
  3517.     s_close() on a socket you have released because it is no
  3518.     longer owned until it is s_inherit()ed. Once socket 's'
  3519.     is released, the socket descriptor 's' will be reused.
  3520.  
  3521.    INPUTS
  3522.     s    - socket descriptor
  3523.  
  3524.    RESULT
  3525.     sockptr - really a pointer to an internal socket structure
  3526.           NULL on failure
  3527.  
  3528.    EXAMPLE
  3529.     sockptr = s_release (s);
  3530.     / * start a new program and pass socket on command line * /
  3531.     sprintf (cmdbuf, "run >nil: %s %ld", cmd_name, sockptr);
  3532.     Execute (cmdbuf, 0, 0);
  3533.  
  3534.    NOTES
  3535.     Use with caution.  Don't release a socket unless another
  3536.     process will s_inherit() it.
  3537.  
  3538.     You _really_ don't want to do this to a socket which has
  3539.     had a s_dup() or s_dup2() executed against it, without
  3540.     being _very_ careful.
  3541.  
  3542.    BUGS
  3543.  
  3544.    SEE ALSO
  3545.     s_inherit()
  3546.  
  3547. socket.library/s_syslog                               socket.library/s_syslog
  3548.  
  3549.    NAME
  3550.     s_syslog - log system messages
  3551.  
  3552.    SYNOPSIS
  3553.     error = s_syslog (priority, message)
  3554.     D0          D0        A0
  3555.  
  3556.     int s_syslog (int, char *);
  3557.  
  3558.    FUNCTION
  3559.     s_syslog() writes the 'message' argument to a console window and/or
  3560.     a specified file. The priority field is used to determine which,
  3561.     if any, of the above options is used.
  3562.  
  3563.     The file "inet:s/inet.config" contains the optional fields:
  3564.  
  3565.       filepri     - msgs w/pri >= filepri are sent to file.
  3566.       windowpri     - msgs w/pri >= windowpri are sent to window.
  3567.       syslogfilename - the path/name of the file for filepri messages.
  3568.       syslogconsole  - a console window definition
  3569.  
  3570.     Example:  (Note: this is the exact format to use in the
  3571.              'inet:s/inet.config' file.)
  3572.  
  3573.       filepri=5
  3574.       windowpri=3
  3575.       syslogfilename=t:foobar
  3576.       syslogconsole=CON:0/0/600/70/ SYSLOG /AUTO/CLOSE
  3577.  
  3578.       These entries tell s_syslog how to deal with the messages it is
  3579.       sent.  Note that the smaller the priority number, the greater
  3580.       it's priority. Therefore, a message of priority 3 is of greater
  3581.       importance than a message of priority 4. If you do not add these
  3582.       fields to your 'inet:s/inet.config' file, the default values will
  3583.       be used. The default values are:
  3584.  
  3585.           windowpri = 4
  3586.           filepri    = 3
  3587.           syslogfilename = RAM:syslog.dat
  3588.           syslogconsole  = CON:0/0/600/70/ SYSLOG /AUTO/CLOSE/INACTIVE/WAIT
  3589.  
  3590.       The above values mean:
  3591.  
  3592.         1. A message sent with a priority >= 4 (4,3,2,1,0) will
  3593.            be sent to BOTH the console window and the file
  3594.            'RAM:syslog.dat'.
  3595.  
  3596.         2. A message sent with a priority >= 3 (3,2,1,0) will
  3597.            be sent to ONLY the console window.
  3598.  
  3599.         3. A message sent with a priority < 4 (5,6,7,8) will
  3600.            be ignored.
  3601.  
  3602.    INPUTS
  3603.     pri      - an integer value between 0-7
  3604.     message   - a string to be written to the console window and/or
  3605.             the syslog file.
  3606.  
  3607.    RESULT
  3608.     error      -   0 (zero) is returned if everything went well.
  3609.           -  -1 is returned if anything went wrong.
  3610.  
  3611.       If an error has occurred, you need to examine your errno value
  3612.       to determine just what went wrong. It is possible, for example,
  3613.       to have a write to the console window succeed while a write of
  3614.       the same message to the file failed.    The various error values
  3615.       that occur during the syslog operation are OR'd together and
  3616.       returned in 'errno'. See the file "sys/syslog.h" for the values.
  3617.  
  3618.       Example:
  3619.  
  3620.       #include<sys/syslog.h>
  3621.          ...
  3622.       extern int errno;
  3623.       int error;
  3624.  
  3625.        error = s_syslog (5, "This is a test\n");
  3626.        if (error == -1)
  3627.        {
  3628.           if (errno & SYSLOGF_WINDOWOPEN)
  3629.           {
  3630.          printf ("Could not open syslog window\n");
  3631.           }
  3632.           if (errno & SYSLOGF_FILEWRITE)
  3633.           {
  3634.          printf ("Could not write to syslog file\n");
  3635.           }
  3636.        }
  3637.  
  3638.    NOTES
  3639.     1. s_syslog () will clear the global errno value with each call.
  3640.  
  3641.     2. Use syslog () to send printf-style arguments (at a higher
  3642.        overhead).
  3643.  
  3644.     3. The maximum length of a syslogfilename line in inet.config is
  3645.        256 characters. This includes the 'syslogfilename=' portion
  3646.        of the line.
  3647.  
  3648.        maxlen (path/filename) = 256 - len ("syslogfilename=")
  3649.  
  3650.        Similarly for syslogconsole.
  3651.  
  3652.    BUGS
  3653.     none known
  3654.  
  3655.    SEE ALSO
  3656.     inet.config (in the I-Net 225 manual)
  3657.  
  3658. socket.library/umask                                     socket.library/umask
  3659.  
  3660.    NAME
  3661.     umask  -- get and set user file creation mask
  3662.  
  3663.    SYNOPSIS
  3664.     #include <sys/types.h>
  3665.  
  3666.     umask = umask (cmask)
  3667.     D0           D0
  3668.  
  3669.     mode_t umask (mode_t);
  3670.  
  3671.    FUNCTION
  3672.     The umask() function sets the file creation mask to 'cmask'
  3673.     and returns the old value of the mask.
  3674.  
  3675.    RESULT
  3676.     -1 will be returned and an error message will be displayed
  3677.     if there is a problem reading the current configuration.
  3678.  
  3679.    EXAMPLE
  3680.  
  3681.    NOTES
  3682.     Amiga filesystems, of course, will not use this file creation
  3683.     mask.  We use it for NFS, and provide it in case you can think
  3684.     of something to use it for.
  3685.  
  3686.     The new mask value is not saved to the configuration file. It
  3687.     will be reset when the machine is rebooted.
  3688.  
  3689.     Currently, configuration information is stored in memory in a
  3690.     configuration structure.  This structure is initialized when
  3691.     the network functions are started, and the data comes from
  3692.     "INet:s/inet.config".
  3693.  
  3694.    BUGS
  3695.  
  3696.    SEE ALSO
  3697.     getumask()
  3698.  
  3699.